This page implements an electronic version of an ACBL Convention Card. On this page you can:

• Easily compose custom convention cards
• Print attractive copies of cards you create
• Store your customized cards for future change and reuse
• Explore on-line documentation to get a better understanding of conventions that can help you bid and play more effectively.

Like other tools of this kind you can compose your card by setting options and filling text fields directly on screen. You can also use macro buttons to rapidly compose your card based on knowledge built-into the Editor. Throughout the process the Editor cross checks your entries to ensure that your card is error-free. Once completed, you can print the card so you can have it handy at the tables. Cards may be saved, typically for different partnerships that you may have. You can reopen saved cards for further modification, sharing, and reprinting. This document describes how you interact with the page in order to access these features.

To begin let us first describe the page layout. At the very top there is a Title Area that appears as:

This includes the name of the page on the left and buttons on the right that allow you to

1. Sign In or Register (or Logout)
2. Access the User Guide
3. and Explore the tool's Admin Guide.

Many of the features found on this page can be used without having to Sign In - doing so is completely your option. You can compose a card in seconds and print it as a guest user. To save, open, and delete cards however, you must first Sign In and, of course, to Sign In you must first create an account. This is easy! To Sign In or to create an account (Register) click on the Sign In or Register button, fill the requested fields on the dialog box that appears, and click Sign In again.

Below the title area is a Command Area that holds a collection of function buttons arranged in groups and subgroups. Here is a snapshot:

At the bottom of the page you see the convention card itself.

The first row of the command area is labeled commands and contains buttons that allows access to high-level functionality such as Opening, Saving, and Printing cards. The remaining rows of the command area contain buttons that are used quickly and accurately compose popular conventions.

To be able to save and open cards you must log in. Cards are saved in a database based on your username and the names you have specified for the card. This allows you to quickly identify cards you share with a partner.

To print copy of a card simply click the Print button. You do not need to be logged in to to print!

There is also a button labeled “Min/Max” on the first row in the Command Area. Min/Max is used to change the presentation of the convention card between the default max view that displays the entire convention card and a minimized min view. In the min view only the settings that have been selected and/or set are displayed. This can be useful in ensuring that the card will be considered “adequately filled”.

Export is an advanced feature used by administrators to compose new conventions. General users can happily ignore this command. Administrators can read more about the use of Export in the Admin Guide.

The remaining rows of buttons in the command area are Macro Button that exercise the built-in intelligence of the tool. These are described in greater detail below.

At the bottom of the page an interactive version of the standard Convention Card is shown. This can be edited directly by selecting checkboxes, radio button and completing text fields. This may be familiar since this is the way other tools operate and, to some degree, how one completes a paper-based card.

Below the first row of buttons in the Command Area are Macro Buttons. These buttons encapsulate knowledge of various sets of named conventions and are used to quickly and accurately configure settings according to these pre-defined standards. This transforms the compositon process from a daunting endeavor to a much simpler process. Each button can automatically encode the chosen convention, configuring dozens of options, in a single click.

The there are two kinds of Macro Buttons: complete sets and individual conventions. Both kinds are programmed to configure any or all of the items on the convention card. The key difference between complete sets and individual conventions regards how they operate with respect to existing settings on the current card. Complete Sets reset the card to blank before applying their settings. Individual Conventions, on the other hand, apply their settings as a layer (incrementally) to the current card configuration. The operation of both kinds are complementary as the preferred method of composing a new card is to first select a complete set, then layer on modifications using individual conventions per your partnership agreement.

As we now know and review by example, Complete Sets of conventions are configured by pressing a single button such as SA Yellow Card to configure the Standard American Yellow Card. The logic provided first resets the card to an original (blank) state then applies as many specific settings to encode the complete Yellow Card convention. This makes it quick, easy and foolproof to compose standard cards in seconds. Once selected these complete sets provide a solid foundation for incremental adjustment using the Individual Convention Macros and/or direct articulation on the card itself.

Individual Conventions for {style, openings, responses, overcalls, carding,...} allow you to incrementally add conventions as necessary. These Individual Convention Macros apply as many specific settings to encode the convention without first resetting the card. This allows composition of a completed card in an incremental manner – again making it quick, easy, and foolproof.

As settings are made the background color of the Macro Buttons reflect whether they are effectively selected. To explain, as you complete the card the page cross checks your entries. If the current configuration collectively matches any of the pre-configured Macro Button settings then the corresponding button's background is greyed to reflect the effective selection of the macro.

For example, the Michaels Cuebid requires setting three radio buttons: in DIRECT CUEBID the two radio buttons (Minor & Major) on the Michaels line and in NOTRUMP OVERCALLS the "2 Lowest" radio button on Jump to 2NT line. Clicking on the Michaels Macro button will make these settings. On the other hand if you select the three buttons directly on the card the logic of the page will deduce that you have effectively selected Michaels Macro Button as well. In either case the Michaels button background will be greyed as feedback.

Since Macro Buttons can affect many — even dozens of — card settings having a means to undo their action is important. To implement this feature Macro Buttons are designed to operate as toggles. Each odd click sets and each even click resets (clears) the configuration underlying a button.

Help Hotspots are highlighted with a text shadow such as SPECIAL DOUBLES. Clicking on a Help Hotspot opens documentation describing that specific area as an aid in understanding how to fill out the particular section. The help documentation references learning materials provided at acbl.org.

The Editor includes other built-in capabilities that make filling out a card easy while also cross checking for accuracy. In particular, fields that are intended to contain bids, such as the limit of Negative Doubles, use drop down lists with appropriate (legimate) values. Fields that expect entry of the number of high-card points for openings and overcalls, for example, also have built-in, drop-down, values. Exclusive settings are implemented as radio buttons so selecting one choice automatically resets (clears) all the other related radio buttons. Semi-exclusive settings are implemented as associated checkboxes that operate as a blend of radio-style and checkbox-style semantics as is appropriate based on your selections. Similarly, checkboxes and text input fields that define a common aspect on the card are synchronized so that, for example, if the text field is comleted the checkbox is automatically selected and vice versa. Briefly: the tool tries to ensure input can be done quickly while also maintaining integrity.

Many thanks are due to the ACBL for their excellent teaching resources. Thanks also to other programming pioneers that provide similar applications and tools to the bridge community. Finally and of course thanks to the various master players that invented the conventions bridge players worldwide learn, use, and refine every day. The standards, documents, tools, and innovation help improve the game; making it more challenging and enjoyable.

In this spirit, I created this page to fill a gap that I perceived; adding intelligence to the card composition process. This tool is simple to use, doesn't require a complicated (or costly) download / installation process, and is easily extensible to future innovation. I hope you find the page useful. If you do and would like to pay if forward please consider making a small contribution to my great granddaughter’s college fund. You can easily make such a gift for Izabella here. I thank you for your consideration! Play well and be kind. Kind regards, Richard Smolucha

The power of this tool is a function of its programming. Don't let the word programming scare you! Programming is how the tool gets the knowledge it needs to act intelligently. Extending the knowledge in the tool is simple.

JavaScript is the programming language used to implement the tool. You don't need to know all of JavaScript to program knowledge, just a little. Specifically you only need to understand the concept of Arrays and how to assign values to them.

Arrays are a very common type of structure in programming languages. The closest physical analog to the Array is a list. Think of a shopping list. It might look like:

• Flour
• Cheese
• Salt
• Wine

You might write this on a piece of paper and off to the supermarket to shop. If you wanted to store this list in a JavaScript Array you can create the following code: shopping_list = Array('Flour', 'Cheese', 'Salt', 'Wine'); Technically this specifies that the variable shopping_list will reference an object of type Array that contains four (4) elements with the values "Flour", "Cheese", "Salt", and "Wine" respectively. As an alternative the programmer can use a shortcut as in: shopping_list = [ 'Flour', 'Cheese', 'Salt', 'Wine' ]; Notice how the brackets '[...]' replace the 'Array(...)' in the original. Once the array is thus initialized the program can reference elements in the array using their ordinal index number as in: alert(shopping_list[2]); This will post an dialog box with the word "Salt" (contents of shopping_list element 2). If you understand this you're ready to create one-dimensional Arrays in JavaScript!

Sometimes a list might have sub-lists. Your shopping list might include some additional details like:

• Cheeze
• Ricotta
• Mozzarella
• Wine
• Pinot Grigio
• Barolo

In JavaScript a sub-list is encoded as an item in the shopping_list = [ 'Cheese', [ 'Ricotta', 'Mozzarella' ], 'Wine', [ 'Pinot Grigio', 'Barolo' ] ]; You could do this sub-listing to indefinitely levels (lists with sub-lists with sub-sub-lists ...). Fortunately for the Intelligent Convention Card Editor only uses two-dimensional lists. In particular, the Editor uses the following Array structure to define the knowledge it needs: new_convention = [ [ 'name of field0 on the card', 'value for the field0 on the card' ], [ 'name of field1 on the card', 'value for the field1 on the card' ], ... [ 'name of fieldn on the card', 'value for the fieldn on the card' ], ]; The field_s on the card are all of the text input, checkbox, radio button, and cards (in the Leads area). Each of these has a unique name. In the case of text fields, generally, the value is an arbitrary string. For all the others {checkbox, radio, and cards} there are pre-defined acceptable values. For example the Jump Overcall radio button group is named jump_overcall and can take any value from {strong, intermediate, weak} So if you knew all the names and all the acceptable values you could craft the JavaScript Array for a new convention by hand.

Luckily you don't have to do all that learning and take on the tedious typing needed to write the necessary code. Instead you can simply use the usual interface to complete those items needed for you convention then use the button and the tool will write the code for you! Here's the code that the tool generates for the 5-card major convention using this process: var settings = [ [ 'major_opening_1st2nd', '5'], [ 'major_opening_3rd4th', '5'], ]; Now you can create the definition of a convention pretty easily. In order to use the new convention in the tool it needs to be integrated; adding it as a new macro button in the tool. Before we look at how integration is done let's discuss how individual conventions can be combined to create higher level ones; thereby reducing code maintenance and the possibility of errors and redundancy.

There are an already predefined collection of conventions built-in and tested in the tool. You can easily reuse these to compose additional, compound conventions. By example assume we have the following code that defines the short club opening and our five card major opening: var short_clubs = [ [ 'ga_text', ' Short Club'], [ 'minor_opening_1c', 'short'], [ 'minor_opening_1d', '4'], ]; var five_card_major = [ [ 'major_opening_1st2nd', '5'], [ 'major_opening_3rd4th', '5'], ]; We can compose the combination of the five_card_majors and short_clubs conventions by concatenating them to create a new, higher level convention such as: var five_card_majors_and_short_clubs = [] .concat(five_card_majors) .concat(short_clubs); This uses the JavaScript Array method concat. The operation is analogous to your taping two of your shopping lists together to make a larger list. You don't run the risk of forgetting something or doubling up on items that you would have if you transcribe the two lists. A more practical example (using other predefined individual conventions) is: var standard_american = [] .concat(five_card_majors) .concat(weak_twos) .concat(strong_2_clubs) .concat(weak_twos) .concat(limit_raises) .concat(standard_notrumps) .concat(stayman) .concat(jacoby_transfers) .concat(gerber) .concat(standard_carding);

Once you have defined a new convention you need to add it to the command area as a macro button so that it can be used. To do this you need to add an Object in the menu choices array.

Sorry but I lied. You need to learn one other JavaScript concept to a very fundamental level namely Objects. Simple Objects are very similar to Arrays. The difference is the index used to reference an item in the Array/Object. In Arrays items are indexed by the ordinal number of their position in the list where the first item is referenced as your_array[0]; 0 being the index. You can conceptually consider that the index is implicit and you could define an array explicitly as: shopping_list = [ 0: 'Flour', 1:'Cheese', 2:'Wine' ]; In Objects items are defined in terms of and indexed by their property names. Here is another way to specify the shopping_list: shopping_list = [ "Zero": Flour, "One": 'Cheese', "Two", 'Wine' ]; // or shopping_list = { "Zero": Flour, "One": 'Cheese', "Two", 'Wine' }; From this you can see a lot of similarity. An Array of Objects is used by the Editor for a number of technical reasons but fundamentally to keep the code elegant and simple. With this behind us let's look at how the macro buttons are programmed. It's best to start this by example: Here is the entry for the Standard American convention: { label : "Standard American", set : standard_american, reset : true, ga : {set:"Standard American"} }, Here you see the following fields:

label	This is the text label that will appear in the command area. It should be short and yet descriptive.
set	This is the name of the variable that defines the convention.
reset	This is optional. When it is present and set to true the tool is instructed to reset ALL the fields on the form to blank before applying the convention. Obviously this is intended for complete convention sets.
resets	This is optional. When it is present and set to true the tool is instructed to reset specific fields on the form based on the reset convention. This is intended for use in complex areas such as the specification of defensive no-trump bidding.
ga	This is also optional. It is used to articulate the "General Approach" text field. This capability should be used sparingly since the text field has limited space. The ga Object has the following properties (corresponding to the named groups in the choices Array: set The Name of the Complete Set used (if any) e.g., "standard American" style Describes the bidding style e.g., "aggressive" minors Describes the minor openings strategy e.g., "better minor" carding Describes the defense carding e.g., "upside/down" discards Describes 1st discards e.g., "odd/even"

For most conventions you only need to supply the set and label and you're off and running!

The choices Array is arranged into Groups and Subgroups. A new convention likely falls into an already specified subgroup. Generally the decision or where a new convention should be placed into choices[] is straightforward. In the event that a new group and/or subgroup is needed simply add that new categorization using the following as a template: ... {label:"group", set:"your-new-group-name"}, {label:"subgroup", set:'your-new-subgroup-name'}, {label:"your-new-convention-label", set:your-new-convention}, ... Then place this code in the approriate location in the choices Array.

Hopefully these instructions fully and clearly describe how the Editor can be upgraded with new knowledge. Obviously this kind of effort is the domain of tool administrators (especially as regards integrating new conventions - in the role of "editor of the tool") and master players (who might contribute their favorite conventions for example - in the role of "authors of conventions in the tool"). I cannot stress enough the need to carefully test all new conventions before they are integrated into the tool. As for "authors of the tool per se" the best documentation is found in the actual code. The entire project is self-contained in a single PHP script. In other words there is only one file wherein the HTML, CSS, JavaScript are all contained.

I created this page to fill a gap that I perceived in the already-available tools that others had made available previously – adding intelligence and eliminating the need to download and install applications. I hope you find the page useful. If you do and would like to pay if forward please consider making a small contribution to my great granddaughter’s college fund. You can easily make such a gift for Izabella here. I thank you for your consideration! Play well and be kind.