ATG Page Developer's Guide

Tag converters can have a number of format arguments that specify the format of the output.

Required converter

To require a user to populate a field before the form can be processed, you can use the required converter. The required converter takes a Boolean expression and affects only the set operation, and you use it only in form dsp:input, dsp:select, dsp:postfield, and dsp:textarea tags (not in dsp:valueof, dsp:a, or dsp:param tags) to designate that the corresponding field must be filled in. If the value in the field is an empty string or consists of white space, a DropletFormException for this element is thrown.

For example, the following input tag creates a form exception if the user submits the form with a null or empty value in the input field for user name:

<dsp:input type="text" bean="Person.userName" required="true"/>

Note that the date and number converters take required as an optional attribute. For example, this tag specifies a date format, and makes the field required:

<dsp:input bean="NewUser.lastActivityDate" date="MMM d, yyyy"
required="true"/>

Date converter

You determine the way you want dates to be formatted in a form by using the date converter. The date converter uses the formatting and parsing methods and formats of the java.text.SimpleDateFormat class. For example, to format a date as November 12, 1998, use date="MMM d, yyyy". If you want to format the same date as 11/12/98, use date="M/dd/yy". See the API reference for java.text.SimpleDateFormat in your JDK for full details of how the converter parses strings into Dates and formats Dates into strings for display.

Because the date converter does not flag an error if a two-digit value is entered when a four-digit value is expected for the year, you might need to add error checking to your form validation logic to handle this case. Also, if the field expects a two-digit year entry, the year is interpreted as being no more than 80 years before or 20 years after the current date.

This example uses the date converter to format a date:

<dsp:input bean="NewUser.lastActivityDate" date="MMMM d, yyyy"/>

This example defines a parameter that is a Date, not just a String:

<dsp:param name="lastActivityDate" value="3/4/98" date="M/dd/yy"/>

If your form contains a date input field, you might want to place a note near that field instructing users to supply the date in the expected format. If a date is entered in the wrong format, it is interpreted according to the format specified in the date converter, and as a result might store an incorrect date.

mindate and maxdate attributes

You can use the date converter’s optional mindate and maxdate attributes individually or together to restrict the range of dates a field accepts. For example, if you have a field for the user’s birth date, you typically want to require that the user enter a four-digit year to make sure the date the customer enters is unambiguous, as in this tag:

<dsp:input bean="NewUser.birthDate" date="M/dd/yyyy"/>

If users enter a two-digit year instead, the date might be interpreted differently than expected. For example, 2/16/59 is interpreted as February 16, 0059. By using the mindate attribute, however, you can reject dates that are earlier than a certain date you specify. For example, the following tag includes a mindate (in the format specified by the date attribute) of January 1, 1900:

<dsp:input bean="Employee1.birthDate" date="M/dd/yyyy"
 mindate="01/01/1900"/>

In this case, if the user enters 2/16/59, the entry is rejected, because February 16, 0059 is earlier than the date specified by mindate.

When a user enters a date that is outside of the bounds specified by mindate and maxdate, the converter rejects the value and throws a TagConversionException with an invalidDate error code. You can include error handling in your form to display a message instructing the user to enter a valid date.

Number Converter

You determine the way you want numbers to be formatted in a form by using the number converter. The number converter uses the formatting and parsing methods and formats of the java.text.DecimalFormat class. For example, to truncate any decimals in a number, use number="#". To display a number using comma as a grouping separator, and with up to two decimal places, use number="###,###.##". To ensure that exactly two decimal places are displayed, even if the decimal digits are zero, use number="#.00". See the API reference for java.text.DecimalFormat in your JSDK for full details about how the converter parses strings into numbers and formats numbers for display.

The following example displays a number with two decimal places and at least one digit before the decimal point (even if any of the digits is zero):

<dsp:valueof bean="CurrentPitcher.earnedRunAverage"
number="0.00"></dsp:valueof>

Nullable Converter

If a user leaves a form field empty, by default the ATG platform does not call the setX method to change the value of the corresponding property. For example, your site might have a form where registered users can update their profiles, and includes a text field for entering a new home address. If the user leaves this field blank, the property that stores the address remains unchanged.

In some cases, you might want a blank form field to indicate that the corresponding property should be set to null. You can set the nullable converter to an expression of true to do this. For example:

<dsp:input type="text" bean="Person.address" nullable="true"/>

Primitive data types (such as int) , however, cannot be set to null. If you use the nullable converter with a property whose data type is a Java primitive, and the user leaves the field empty, an exception is thrown. You should use the nullable converter only with data types that are classes (such as Integer).

Like the required converter, the nullable converter can be used in conjunction with the date and number converters. For example, this tag specifies a number format, and makes the field nullable:

<dsp:input bean="NewUser.age" number="#" nullable="true"/>

Escape HTML Converter

When a JSP is converted into HTML by the page compiler, all values provided by DSP tags are automatically enclosed in escape tags so they are treated as non-HTML code. This means that text is rendered as raw text:

This is how you code a word to appear <b>bold</b>.

rather than formatted HTML:

This is how you code a word appear bold.

In most circumstances, you want tag values to be displayed as literal text. However, when you want a tag value to appear as formatted HTML code, use the valueishtml tag converter. This tag converter accepts a Boolean value.

<dsp:param name="boldCode" value="<b>bold</b>"/>
Bold text looks <dsp:valueof param="boldCode" valueishtml="true"/>.

In a browser, this tag displays as:

Bold text looks bold.

CreditCard Converter

You can display a credit card number as a series of number groupings. You determine the number of items in each grouping by setting the groupingsize attribute. For example:

<dsp:valueof bean="CreditCard.number"converter="creditCard"
groupingsize="4"/>

This example might render a credit card number that appears as 7845 5624 5586, with four numbers in each grouping.

In general, you only want full display of a credit card number when a user enters it initially in order to facilitate visual confirmation. Afterward, you might only want to display portions of it so a user can recognize it without jeopardizing the user’s privacy. With numcharsunmasked, you can indicate how many numbers you want to unmask, counting from right to left. The masking character is X, unless you specify otherwise using the maskcharacter attribute.

Here are some examples:

Currency Converters

The currency, currencyConversion, and euro converters parse and convert currency amounts.

For example, to format a value as a currency amount:

<dsp:valueof bean="PriceInfo.amount" converter="currency"/>

In this example, the value in amount is translated into the currency pattern of the recognized locale. If no locale is specified, the converter first looks for a request parameter named locale, which can be either a java.util.Locale object or a String that names a locale. If this parameter cannot be found, the converter gets the locale from the RequestLocale.

The following example explicitly specifies a locale:

<dsp:valueof locale="en_US" bean="PriceInfo.amount" converter="currency"/>

This example might display a value of $13.89. There is a default setting for each locale that determines:

For more information on tailoring your site to an international audience, see the Internationalization chapter in the ATG Programming Guide.

euroandcurrencyConversion

If you need to display prices in more than one currency on your site, the euro and currencyConversion converters are especially useful. These converters are child classes of the currency converter. You can store prices in Euros, and then use the currencyConversion converter to automatically convert the prices to another currency. For example:

<p>Price in Euros:  <dsp:valueof locale="it_IT"
bean="PriceInfo.amountInEuros" converter="euro" symbol="&euro"/>
<p>Price in Italian lire:  <dsp:valueof locale="it_IT"
bean="PriceInfo.amountInEuros" converter="currencyConversion"/>

In this example, the first dsp:valueof tag displays the price in Euros. The symbol attribute is used to specify the HTML entity for the euro symbol because the ISO Latin-1 (ISO 8859-1) character set does not include this symbol. The locale attribute is used to determine how to format the output. The second dsp:valueof tag displays the price in Italian lire, using the official exchange rate set by the European Union and published at http://europa.eu.int. (The exchange rate is stored in the resource file atg/droplet/ExchangeRates.properties.)

If the locale indicates a country that does not use the euro (such as the United States), these converters return null, and the dsp:valueof tag returns its default value. For example:

<dsp:valueof bean="priceInfo.amountInEuros"
converter="currencyConversion">$5.00</dsp:valueof>

In this tag, the locale attribute is not specified, so locale is determined as described above. If the locale is a country that uses the euro, the value of priceInfo.amountInEuros is converted to the appropriate currency (using the official exchange rates) and displayed in the appropriate format for that locale. If the locale is not a country that uses the euro, the price is displayed as $5.00.

The currencyConversion tool also includes a reverse attribute that you can use to convert from a locale-specific European currency (for example, German marks) into Euros. Again, the conversion is performed using the official EU rate.

<dsp:valueof locale="de_DE_EURO" bean="priceInfo.amountInEuros"
reverse="true" converter="currencyConversion" symbol="&euro;">no
price</dsp:valueof>

In this example, the amount stored in priceInfo.amountInEuros is converted to Euros and the optional symbol attribute is used to display the euro character. In addition, the de_DE_EURO value tells it to format the euro value appropriately for the specified locale (Germany, in this case).

See the Internationalization chapter of the ATG Programming Guide for more information about locales.