You can create your own custom tag converter. To add your own converter, follow these steps:
Create a new class that implements the
atg.droplet.TagConverterinterface. This class must implement the four methods described below under TagConverter Methods.Call the
TagConverterManager.registerTagConvertermethod with an instance of this class. Note that this call must be made before your converter is used by a JavaServer Page. Make sure that you add this code to a class that gets initialized during the startup process of your module (i.e. is in theInitialservices list).A new tag converter can support any number of attributes. Create attributes by making an instance of the
TagAttributeDescriptorclass. Be sure to populate thenameproperty to avoid aNullPointerException.Add a
<dsp:valueof>,<dsp:input>, or<dsp:param>tag to the page that uses this converter.
For more information about creating and using tag converters, see the atg.droplet.TagConverterManager entry in the ATG API Reference or the Tag Converters section of the Creating Java Server Pages chapter of the ATG Page Developer's Guide.
TagConverter Methods
A TagConverter class must implement the following four methods of the atg.droplet.TagConverter interface:
getName
Returns the name of your converter. This is the name that is used as an argument to the converter attribute in a tag. For example, Dynamo has a converter whosegetNamemethod returnscurrency, so you can include a tag like this in your JavaServer Pages:<dsp:valueof param="myPrice" converter="currency"/>getTagAttributeDescriptors
Returns the list of attribute arguments that this converter takes. These attributes are listed along with theconverterattribute in yourvalueof,input, orparamtag. These attributes can be marked as optional if they are not required. For example, thecurrencyconverter takes alocaleattribute that is optional. The default behavior if this attribute is missing is to use the locale associated with the current request.A
TagAttributeDescriptoralso can be marked asautomatic, which means that this attribute implies the use of this converter, even if the converter attribute is not specified. For example, thecurrencyconverter defines acurrencyattribute that is automatic, so you can use this converter in your page with:<dsp:valueof param="myPrice" currency/>You cannot have more than one converter registered with the same automatic attribute. You can replace an existing converter by registering a new one with the same name (after the existing converter has already been registered).
It is legal to define a
TagConverterthat takes the same attribute as anotherTagConverteras long as it is not ambiguous which converter to use for a given tag. Therequiredattribute is an automatic attribute for theRequiredTagConverter. TheDateTagConverterhasdateas an automatic attribute andrequiredas an optional attribute. If you use bothdateandrequiredin the same tag, theDateTagConverteris used. If you use justrequired, theRequiredTagConverteris used.convertStringToObject
This method is called in two circumstances:If you are using an
inputtag, when that form value is submitted, this method is called before thesetXmethod of the component is called. YourconvertStringToObjectmethod must generate theObjectvalue for use in thesetXmethod. It can throw aTagConversionExceptionif an error occurs during the conversion process.The
convertStringToObjectmethod for most tag converters returns null if a form field is left empty. If this method returns null, thesetXmethod for the corresponding property is not called, and the current value remains unchanged. If, instead, you want your tag converter to set the value to null when a field is left empty, yourconvertStringToObjectmethod must return the special valueTagConverterManager.SET_AS_NULL. This value instructs thesetXmethod to set the property value to null.This method is also called if you use this converter with a
paramtag when the value of the parameter is defined.
convertObjectToString
This method is called in two situations:When you use a converter in a
valueoftag, this method is used to convert theObjectvalue into aStringvalue before displaying it.When you use this tag in an
inputtag with abeanattribute and no existingvalueattribute, this method is called to fill in thevalueattribute with the current value of the bean property.
