ATG Page Developer's Guide

Several different form controls can set the values of scalar properties, depending on the data type of the property, and whether you want to provide the user with a predetermined set of choices.

Checkboxes

Using a checkbox, a user can set the value of a Boolean property. For example, the Student_01 component might have a property called emailOK that indicates whether your site can send promotional email. Users can indicate their preference on a registration form that contains this input tag:

<dsp:input 
   bean="/samples/Student_01.emailOK" type="checkbox"/>Send email

The current value of the property emailOK sets the checkbox’s initial display: checked (true) or unchecked (false). To override the initial setting, set the checked attribute to true. For example, you might want the checkbox to be checked when the page displays, regardless of the property’s current setting . The input tag looks like this:

<dsp:input 
   bean="/samples/Student_01.emailOK" type="checkbox" checked="true"/>Send email

You can also use the default attribute to specify a value for the input element to display, in the event the property has no value:

<dsp:input 
   bean="/samples/Student_01.emailOK" type="checkbox" default="true"/>Send email

Radio Buttons

To create a set of radio buttons, set a dsp:input tag’s type attribute to radio. The following example uses a group of radio buttons to present users with a set of choices, for setting the favoriteSport property:

<p>Choose your favorite outdoor sport:
<dsp:input bean="/samples/Student_01.favoriteSport" 
   type="radio" value="swimming"/>Swimming
<dsp:input bean="/samples/Student_01.favoriteSport" 
   type="radio" value="biking"/>Biking
<dsp:input bean="/samples/Student_01.favoriteSport" 
   type="radio" value="hiking"/>Hiking
...

In contrast to standard HTML, the name attribute is optional; grouping is based on sharing the same bean attribute—in this example, Student_01.favoriteSport.

Unless you specify otherwise, the page is initially displayed with the current value of favoriteSport, assuming it matches one of the five options specified here. You can override this behavior by using the checked attribute. The previous example can be modified so the hiking radio button is initially selected no matter how the favoriteSport property is set:

<p>Choose your favorite outdoor sport:
<dsp:input bean="/samples/Student_01.favoriteSport" 
   type="radio" value="swimming" checked="false" />Swimming
<dsp:input bean="/samples/Student_01.favoriteSport" 
   type="radio" value="biking" checked="false" />Biking
<dsp:input bean="/samples/Student_01.favoriteSport" 
   type="radio" value="hiking" checked="true" />hiking
...

Within a selection group, only one input tag can set its checked attribute to true; all others must set their checked attribute to false.

The default attribute specifies a value to use if the component property has no value. To specify a value as the default, set the default attribute of its input tag to true, and set default to false for all other input tags:

<p>Choose your favorite outdoor sport:
<dsp:input bean="/samples/Student_01.favoriteSport" 
   type="radio" value="swimming" default="true" />Swimming
<dsp:input bean="/samples/Student_01.favoriteSport" 
   type="radio" value="biking" default="false" />Biking
<dsp:input bean="/samples/Student_01.favoriteSport" 
   type="radio" value="hiking" default="false" />hiking
...

Drop-Down Lists

To create a set of choices in a drop-down list, use a dsp:select tag. For example:

<dsp:select bean="/samples/Student_01.favoriteSport">
  <dsp:option value="swimming">Swimming</dsp:option>
  <dsp:option value="biking">Biking</dsp:option>
  <dsp:option value="hiking">Hiking</dsp:option>
  ...
</dsp:select>

Unless you specify otherwise, the control displays the bean’s current value as the initial selection.. To override this behavior, set the dsp:select tag’s nodefault attribute together with the dsp:option tag’s selected attribute. For example, the following tags specify climbing as the initial selection regardless of the current value in favoriteSport:

<dsp:select bean="/samples/Student_01.favoriteSport" nodefault="true">
  <dsp:option selected="false" value="swimming">Swimming</dsp:option>
  <dsp:option selected="false" value="biking">Biking</dsp:option>
  <dsp:option selected="true" value="hiking">Hiking</dsp:option>
  ...
</dsp:select>

Only one dsp:option tag can set selected to true; the others must set it to false.

Note: Use the nodefault attribute only to ignore a property’s current value. If a form gathers data for a property that has no value—for example, for a new user profile—you can omit the nodefault attribute and set the desired selection through the selected attribute only.

dsp:select can also be used to create a Multiple-Selection List Box, through its multiple attribute.

Text Entry Fields

You can create text entry fields with two DSP library tags:

dsp:input creates a text entry field that is primarily used to enter text values; it can also be used for other types of data. For example, you can associate a text field with a property whose data type is Integer, such as Student_01.age. On form submission, the ATG platform converts the value from a String to the appropriate data type before it writes the value to the component property. If the conversion fails, the property remains unchanged.

A text input field displays the component property’s current value unless the dsp:input tag also includes the value attribute. The value attribute overrides the property’s current value. In the following example, the dsp:input tag for Student_01.name specifies to display the property’s current value, while the tag for Student_01.age includes a value attribute that specifies the field to show a value of 30:

<p>Name: <dsp:input bean="/samples/Student_01.name" type="text"/>
<p>Age: <dsp:input bean="/samples/Student_01.age" type="text" value="30"/>

The user can change the values that appear in the fields, or leave them unchanged. When the user submits the form, the field entries are written to the specified properties.

dsp:textarea creates a multi-line field where users can enter longer text. For example:

<dsp:textarea bean="/samples/Student_01.evaluation"></dsp:textarea>

dsp:textarea accepts standard HTML attributes such as rows and cols, which set the size of the text area on the page.

The text area initially contains the property’s current value unless you supply the default attribute to override that value. The default text can be a String constant, the value of another property, or a page parameter. For example:

<dsp:getvalueof var="standardEval" bean="ReportCard.summary"></dsp:getvalueof>
<dsp:textarea bean="/samples/Student_01.evaluation" default="${standardEval}"/>

Alternatively:

<dsp:textarea 
  bean="/samples/Student_01.evaluation" default="Enter your evaluation here/>

You can set a textarea’s value between its open and close tags. For example:

<dsp:textarea bean="/samples/Student_01.evaluation">
Enter your evaluation here
</dsp:textarea>

If a dsp:textarea tag uses both methods, the default-specified value has precedence.

Note: To display the current property value, make sure no white space or other characters appear between the open and close tags <dsp:textarea></dsp:textarea>; otherwise, those characters are interpreted as the default and override the property value.