Calling and Registering Filters

So far when discussing filters, we have referred to them by name; messageAddFilterPre gets called for every submitted add-message form, before the form is processed; discussionAddFilterPost is called for every submitted add-discussion form, after the form is processed; emailFilterIndividual is called whenever a single-item email notification is ready to send; and so on.


But it is not necessary for your filters to conform to this naming convention. You can have muliple filters for each filter point in the request life cycle, and you can control the order in which they execute.


In fact it's best practice not to use the default names, especially in highly-customized systems because you run the risk of name collisions. If there are two filters (or any two routines) of the same name, only one of them will load and execute. That's the kind of bug that can drive you crazy because it won't generate an error; your code just won't fire.


You can identify a WCTL macro or WCJS command by any name as a particular filter using the following WCTL directive:


%% filterName.filterRegister(macroName) %%

where filterName is a variable or string literal containing the filter's default name and macroName is a variable or string literal containing your macro or command name. So


%% "messageAddFilterPost".filterRegister("myCustomFilter") %%

will cause the routine myCustomFilter to fire after processing for every submitted add-message form.

Filters execute in the order they are registered. If there is a filter with the default name, it always executes first. There are also commands to deregister a filter, display the entire filter chain, or clear the chain entirely.

It is also possible to add additional filters to any filtered form submission by using a special hidden input field. If you customize the add discussion form with

<input type=hidden name="filter" value="accounting">

then the system will look for filters named discussionAddFilterPre_accounting and discussionAddFilterPost_accounting and, if found, execute them at the appropriate points in the request life cycle after the default and any registered filters.

The combination of registered filters, input form filters, localized filters via the template envelope for a given location (which we have not touched on here) makes it possible to add specific, highly targeted functionality as needed for new/customized objects.