Creating Custom Tag Converters

You can modify the tag converters provided in the Oracle ATG Web Commerce platform; you can also create a custom tag converter in the following steps:

  1. Extend an existing tag converter class or create one that implements interface atg.droplet.TagConverter. The new class must implement the following TagConverter methods:

  2. Optionally, create attributes for the tag converter through an instance of the TagAttributeDescriptor class.

  3. Register the new tag converter with the TagConverterManager (atg.droplet.TagConverterManager) by calling TagConverterManager.registerTagConverter() with an instance of the new tag converter’s class. The tag converter must be registered before a JSP can use it. Include the call to registerTagConverter() in a class that is initialized during the startup process of your module—that is, is in the Initial services list.

getName()

Returns the name of the tag converter that is supplied as an argument to the converter attribute. For example, the getName() method that is implemented by the tag converter class atg.droplet.CurrencyTagConverter returns the string currency. So, a dsp:valueof tag specifies this tag converter as follows:

<dsp:valueof param="myPrice" converter="currency"/>

getTagAttributeDescriptors()

Returns an array of TagAttributeDescriptors (atg.droplet.TagAttributeDescriptor). The constructor for a TagAttributeDescriptor is defined as follows:

TagAttributeDescriptor(String pName,
                       String pDescription,
                       boolean pOptional,
                       boolean pAutomatic)

Each TagAttributeDescriptor is defined with an attribute name and description, and two Boolean properties:

For example, the tag converter class atg.droplet.Warthog defines the two attributes, recommendations and winddirection, and sets their Optional and Automatic properties as follows:

public class Warthog implements TagConverter
{
...
static final String RECS_ATTRIBUTE = "recommendations";
static final String WINDDIR_ATTRIBUTE = " winddirection";
...
private final static TagAttributeDescriptor[] sTagAttributeDescriptors = {
    new TagAttributeDescriptor(RECS_ATTRIBUTE,
        "A string for recommendations",
        false, false),
    new TagAttributeDescriptor(WINDDIR_ATTRIBUTE,
        "A string for wind direction",
        true, false),
}

Note: Two constraints apply to custom tag converter attributes:

convertStringToObject()

This method is called when a tag converter is used by one of the following DSP tags:

dsp:input

On form submission, convertStringToObject() is called before the target property’s setX method is called. convertStringToObject() creates the Object value for use by the property’s setX method. The method can throw a TagConversionException if an error occurs during the conversion process.

convertStringToObject() typically returns null if a form field is left empty. In this case, the target property’s setX method is not called, and its value remains unchanged. Alternatively, this method can specify setting the target property to a null value if the field is empty, by returning TagConverterManager.SET_AS_NULL. This instructs the setX method to set the property value to null.

dsp:param

convertStringToObject() is called when the dsp:param tag defines the parameter’s value.

convertObjectToString()

This method is called in two situations: