There may be occasions when you need to pass additional parameters to a filter in order for the filter to do its work. For example, when filtering collections in a multisite environment, you must specify which sites’ items should be evaluated. To do this, the filtering classes in a multisite environment require two additional pieces of information:
A list of site IDs that defines the set of sites whose items should be evaluated.
A site scope setting that controls whether filtering activity is limited to the specified site(s), limited to sites in a sharing group, or not limited at all.
To facilitate the passing of additional parameters, many of the methods in the atg.service.collections.filter.CachedCollectionFilter and atg.service.collections.filter.ChainedFilter filtering classes accept a pExtraParameters map. pExtraParameters is just a map that allows you to pass additional information to a filter so that it can do its work. All of these methods are overloaded with two signatures, one that uses the pExtraParameters map and another that doesn’t. The method that uses pExtraParameters contains the logic required to perform the given tasks. The method that doesn’t include pExtraParameters simply calls the method that does and passes in a null map. This use of overloading allows code that calls the original methods to continue to function properly while providing the flexibility to include additional filter parameters when needed.
You can choose to populate the pExtraParameters map in any way that makes sense for your implementation, although typically it is done through a combination of servlet bean properties and JSP settings. The example below describes how to pass site ID and site scope parameters to /atg/registry/CollectionFilters/GiftlistSiteFilter, a component that filters gift lists and gift items in a multisite environment. A servlet bean, /atg/registry/CollectionFilters/GiftlistSiteFilterDroplet, creates the pExtraParameters map with the site ID and site scope, and passes it along when it calls GiftlistSiteFilter.
The keys of the map are specified by configuring an
extraParametersNameproperty in the servlet bean’s.propertiesfile. For example, theGiftlistSiteFilterDroplet.propertiesfile defines two keys in thepExtraParametersmap,siteIdsandsiteScope:$class=atg.service.collections.filter.droplet.CollectionFilter
$scope=global
updateCache=true
consultCache=true
extraParameterNames=siteIds,siteScope
filter=/atg/registry/CollectionFilters/GiftlistSiteFilterThe values for each key are set in the JSP. The following example sets values for the
siteIdsandsiteScopekeys defined by theGiftlistSiteFilterDropletservlet bean (note that theGiftlistSiteFilteruses default values whensiteIdsorsiteScopeare not explicitly set by the servlet bean):<dsp:droplet name="/atg/commerce/collections
/filter/droplet/GiftlistSiteFilterDroplet">
<&-- Specify the collection to filter, the site context, and the
site scope. --%>
<dsp:param name="collection" bean="Profile.giftlists"/>
<dsp:param name="siteIds" value="siteA,siteB"/>
<dsp:param name="siteScope" value="current"/>
<dsp:oparam name="output">
<%-- The droplet stores the filtered list it in the JSP parameter
filteredCollection. The getvalueof tag transfers that value
to the JSTL variable filteredGiftlists. --%>
<dsp:getvalueof var="filteredGiftLists" param="filteredCollection" />
<%-- See if the new collection is empty. If not, iterate
through it. --%>
<c:if test="${not empty filteredGiftLists}">
<c:forEach var="giftlist" items="${filteredGiftLists}">
<%-- Do whatever you want to do with each giftlist in here. --%>
</c:forEach>
</c:if>
</dsp:oparam>
</dsp:droplet>Using this key and value information, the servlet bean’s
service()method builds thepExtraParametersmap and passes the map when it calls the filter. In cases where there are no extra parameters in the request, theservice()method calls the original version of the method that doesn’t use thepExtraParametersmap.
Out of the box, the only filter Commerce includes that uses the pExtraParameters map is the GiftlistSiteFilter filter, mentioned above. You can find additional information on this filter, and the servlet bean that calls it, in the Filtering Gift Lists section of the ATG Commerce Programming Guide. Keep in mind that, while the pExtraParameters map was initially developed to support site-aware filters, it can be used to pass any additional parameters that your filters require.
