Creating radio checkboxes with Acrobat 7 and 8

Learn how to create radio checkboxes using Acrobat Forms technology (AcroForms) and LiveCycle Designer.

By Thom Parker – February 12, 2009

 

Scope: Acrobat/LiveCycle Designer 7 & 8
Skill Level: Intermediate
Prerequisites: LiveCycle Forms and JavaScript familiarity

Radio buttons are very useful form-field controls. They provide the user with the simple multiple-choice selections we’ve come to know and love on all those exams we took as schoolchildren, in which we were instructed to “Select one and only one answer.” But if you’re in the form-creation business, you’ve probably run into the situation where you want to give users the option of not selecting any choice. This can be very frustrating. With traditional radio buttons, you can select another choice, but you can’t unselect the current choice. For this we need a new kind of control, what I call the “Radio Checkbox.”

I’ll cover creating a Radio Checkbox in both the traditional Acrobat Forms technology (called AcroForms) and in LiveCycle Designer. Building one in AcroForms is actually quite simple, but I’ll digress a bit and explain some of the inner workings of radio buttons and checkboxes in AcroForms before getting into the actual implementation and complexity of creating the same functionality in LiveCycle forms, which is a bit trickier.

A little AcroForms background

In AcroForms, both checkboxes and radio buttons are really the same thing. They only differ in how they are used. To the user, a radio or check button appears to be either on or off, but under the covers each has an export value that is a text string, not a Boolean value as you might expect. Buttons with the same name are the same control, or to put it another way, they are part of the same group and therefore operate together as a single unit. If the buttons in a group have the same export value, then they turn off and on together. If each button has a different export value, then they operate like radio buttons. Only a single export value is allowed for the group, so only one button can be turned on at a time. This is called mutual exclusion, so radio buttons are also referred to as a “mutual-exclusion group.” One turns on, another turns off. To bring this discussion full circle, the difference between radio buttons and checkboxes in AcroForms is Acrobat does not allow a radio button to be turned off when the user clicks on it with the mouse. Radio buttons can only be turned on, whereas checkboxes can be turned both on and off. Otherwise, they are functionally the same.

How to do it in AcroForms

This setup allows us to create a new kind of control, the Radio Checkbox. In this control, we use checkboxes instead of radio buttons to build our mutually exclusive button group. The checkboxes in this group all have the same field name, but have different export values. This allows users to turn off their radio button selection. If you’re worried about users not understanding they can do this, don’t. Users are always clicking the mouse all over the place. They’ll discover this new functionality quickly enough without explanation. By the way, export values are set in the “options” tab on the properties dialog for the button (see this tip). Remember, I’m talking about AcroForms here, we haven’t gotten to the bit about LiveCycle forms yet. A sample form using Radio Checkboxes is provided here, RadioCheckBox_AcroForm.pdf. <?php makeFileTypeLabel("PDF","47 KB"); ?>

On to LiveCycle Forms

Wow, creating a Radio Checkbox was really easy to do in a traditional PDF form, but these days everyone is making LiveCycle Designer forms. How do you do the same thing in that technology? Well, as you may very well have noticed by now, LiveCycle Designer forms are a very different animal from the old style of PDF forms. LiveCycle Designer and AcroForms are both forms technologies, so naturally there are a lot of parallels. For many users, there are few differences. But (and it’s a BIG But), under the covers they are very different. One of those differences is how radio buttons and checkboxes work. To be specific, form-field naming and export values have a very different meaning in LiveCycle Designer than they do in AcroForms. I’m not going to get into the low-level details, but suffice to say there is no built-in way to do this like there is with AcroForms. We’ve got to use JavaScript to force our Radio Checkbox functionality.

The simplest way to make a Radio Checkbox in LiveCycle Designer is to modify the existing radio-button functionality, so let’s take a closer look at that. First, users place the cursor over one of the buttons in the group, press the left mouse button and then let the left mouse button go. Pressing on the left mouse button is called “Mouse Down” and letting the button go is called “Mouse Up.” The “Mouse-Up” action is what triggers the radio button to change from off to on. If the radio button is already turned on, there is no change. It is the “Mouse-Up” action we need to modify. But, now we run into a problem. By the time the “Mouse-Up” event script is called, the button value has already changed. How do we know the initial state of the radio button? The answer: We use the “Mouse-Down” action to capture the initial state. Below are the two scripts needed on each of the radio buttons in the exclusion group. An example form is provided here, RadioCheckBox _XFA.pdf.[PDF, 298KB] LiveCycle Designer scripts are entered from the Scripting Window, which can be located under the “Window” menu in LiveCycle Designer.

Mouse-Down Action Script to capture initial state

this.initValue = this.rawValue;

The value of the radio-button group is saved to a variable attached to the radio-button object. This value is the export value of the selected radio button. The radio-button object is persistent for the duration of the click operation so there is no problem in placing the value here.

Mouse-Up Action Script to turn off radio button

var localExport = null;
for(var i=0;i<this.nodes.length;i++){
	if(this.nodes.item(i).className == "items"){
		localExport = this.nodes.item(i).nodes.item(0).value; break;
	}
}
if(this.initValue == localExport ) this.rawValue = 0;

The first nine lines of this code acquires the export value of the radio button. The export value of each individual radio button is contained in an “items” list much like items in a list or combo box. For a radio button, the list has a single entry. The fancy search loop is necessary to support Acrobat 7. This can be done with a single line of code in Acrobat 8. If the export value matches the initial value then we know this radio button is already on. The next two lines of code test the button’s value and reset it if there is a match.

Now we’ve created Radio CheckBox controls for both AcroForms and LiveCycle Designer forms. Be sure to take a look at the example files.