In most ATG operations, you update a Map property by updating a specific key value as if it were a servlet bean property:
<dsp:input type="text" bean="MyBean.value.addresses.city"/>
While addresses
is a Map property and city
is a key, this tag represents addresses
and city
as properties. Making a change to a key’s value requires entering text into a text box and submitting the operation.
The RepositoryFormHandler
default setting lets you manipulate Maps as lists, providing additional flexibility. To make changes to the keys and values in a Map or set a series of repository IDs as values dynamically, use the RepositoryFormHandler
properties editMapAsLists
and keysAndRepositoryIds
respectively. The keysAndValues
property can also assist in these processes by letting you dynamically update a series of primitive values.
editMapsAsLists
You typically interact with Maps by treating them as servlet beans. For example, to expose a value, you specify the key as an input parameter. You cannot add new key/value pairs when you work with Maps in this way.
Alternatively, you can treat a Map as a list with the RepositoryFormHandler. If the editMapsAsLists
property is set to true, you can use dsp:input
and dsp:setvalue
tags to expose or update a Map’s, as with any list property.
To use this feature:
Make sure
editMapsAsLists
is set to true (the default setting).Insert a reference in your page to the numNewValues property to define the number of keys or values to work with. The default is 0, indicating that the new values overwrite the current values. Include this step only in order to add new values to existing ones.
Set the updateMode property to
append
,prepend
,replace
, orremove
. The default value isreplace
, so only include this tag if for addition or removal operations.Define one or more text boxes that accept values for the Map entry to edit. The value can be a user-entered value or a page parameter that holds a
repositoryId
, which references another repository item.
For example, a Shipping Address page where users can enter additional shipping addresses might include this code:
<dsp:input type="hidden" bean="MyRepositoryFormHandler.value.addresses.numNewValues" value="2"/> <dsp:input type="hidden" bean=MyRepositoryFormHandler.value.addresses.updateMode" value="append"/> Enter Home Address: <dsp:input bean="MyRepositoryFormHandler.value.addresses.keys[0]" type="hidden" value="home"/><br/>Street: <dsp:input bean="MyRepositoryFormHandler.value.addresses[0].street" type="text" value=""/><br/>City: <dsp:input bean="MyRepositoryFormHandler.value.addresses[0].city" type="text" value=""/><br/>State: <dsp:input bean="MyRepositoryFormHandler.value.addresses[0].state" type="text" value=""/><br/>Postal Code: <dsp:input bean="MyRepositoryFormHandler.value.addresses[0].postalCode" type="text" value=""/> Enter Work Address: <dsp:input bean="MyRepositoryFormHandler.value.addresses.keys[1]" type="hidden" value="work"/><br/>Street: <dsp:input bean="MyRepositoryFormHandler.value.addresses[1].street" type="text" value=""/><br/>City: <dsp:input bean="MyRepositoryFormHandler.value.addresses[1].city" type="text" value=""/><br/>State: <dsp:input bean="MyRepositoryFormHandler.value.addresses[1].state" type="text" value=""/><br/>Postal Code: <dsp:input bean="MyRepositoryFormHandler.value.addresses[1].postalCode" type="text" value=""/>
This page supplies a set of four text boxes for each of the two addresses: one is identified by the key home
and the other by the key work
. Because updateMode
is set to append
, the addresses are added to the existing addresses
Map. By setting the numNewValues
property to 2
, the ATG platform creates two key/value pairs for the addresses
Map, which are populated by the values that the user provides through the form. On form submission, the new keys and values are appended to the current values to addresses
.
Note: A Map must have unique keys. If home
and work
already exist as keys in the addresses
property, their values are replaced by the new ones supplied in the form, despite the updateMode
setting.
keysAndRepositoryIds
The keysAndRepositoryIds
property lets you simultaneously set a Map key and value, where the Map value is a multi-valued property that holds a collection of repository IDs. Without keysAndRepositoryIds
, performing this operation requires two input tags.
<dsp:input type="text" bean="MyRepositoryFormHandler.value.favorites.keys[0] value=""/> <dsp:input type="text" bean="MyRepositoryFormHandler.value.favorites.repositoryIds[0] value=""/>
The keysAndRepositoryIds
property lets you accomplish this task with greater flexibility and power. Values saved to the keysAndRepositoryIds
property must follow this format:
key=repositoryId
Note:The separator used in this example is the default value assigned to the mapKeyValueSeparator
property. You can change the recognized separator by updating the value in this property.
You can use page parameters to set dynamic key repository ID values and configure a Format
bean to provide the syntax. For example, you might want to track the brands each customer prefers. Each brand is associated with a business, and one business can maintain several brands; so you want to organize the brands by parent business. Therefore, you display the brands as text boxes. When checked, you want the favorites
Map to save a business name and brand ID as the key
and repositoryId
respectively. You might design your code like this:
<dsp:form action="keysandids.jsp" method="post"> <dsp:input bean="MyRepositoryFormHandler.value.favorites.updateMode" type="text" value="prepend"/> <br/> <dsp:droplet name="/atg/dynamo/droplet/RQLQueryForEach"> <dsp:param bean="/atg/userprofiling/ProfileAdapterRepository" name="repository"/> <dsp:param name="itemDescriptor" value="business"/> <dsp:param name="queryRQL" value="all"/> <dsp:oparam name="output"> <dsp:droplet name="/atg/dynamo/droplet/Format"> <dsp:param name="key" param="index"/> <dsp:param name="repositoryId" param="element.repositoryId"/> <dsp:param name="format" value="{key}={repositoryId}"/> <dsp:oparam name="output"> <dsp:input bean="MyRepositoryFormHandler.value.favorites.keysAndRepositoryIds" paramvalue="message" type="checkbox"/><dsp:valueof param="message">not set</dsp:valueof> <br/> </dsp:oparam> </dsp:droplet> </dsp:oparam> </dsp:droplet> <dsp:input bean="MyRepositoryFormHandler.update" type="submit" value="Update"/> </dsp:form>
The RQLQueryForEach
and the ProfileAdapterRepository
retrieve the brands saved as business items in the repository. Assume that each brand displays in a text box in the page and when it is modified, the Format
bean associates each business name and brand ID to the key
and repositoryId
properties of a Profile component favorites
Map.
keysAndValues
You can configure keys and values that are primitive data types for Maps with the keysAndValues
property. As with the keysAndRepositoryIds property, you do so in the context of a JSP, with a similar format:
key=value
For a detailed example and explanation, see keysAndRepositoryIds.