Using Process Filters
Introduction
Creating a Preferences Process Filter
Sending to a New HTML Page
Troubleshooting
Resources
Next Section
In the previous section, we covered way in which you can use custom variables to create new user information or information about the various documents within the Web Crossing database. But you can also intercept and change the very functions within Web Crossing if you want to, using process filters.
Process filters let you examine form fields and take appropriate action: build a complete page to send to the user, forward the user to a different URL, construct an error message, or do nothing and continue on with normal processing.
Process filters are available for:
As you can see, you can customize almost any process you want to! For a complete list, see the sysop docs.
One of the more common (but more complicated) uses for process filters is for authentication with an outside database. (See the FAQ for more information on the authenticateFilter macro.)
For a simpler example of how filters work, we'll create a preferences process filter.
Creating a Preferences Process Filter
Let's say your users have gotten clever and discovered they can change their "second line," the line of text that appears under the userName above each post. They are trying to outdo each other by posting clever vulgarities. You want to make it impossible for them to do this in the future.
You need a preferences process filter.
(1) The first thing you'll need to do is define your list of objectionable words in the Control Panel > Customizing > General Settings > Moderated Posts. Be sure to read the "Note:" text there which describes how the logic of the objectionable-word checker works.
Type in your list of words separated by spaces, and submit the form. For testing purposes here, we'll use the word "poo" as our vulgar word. (^_^)
|
Note: A side-effect of putting any words at all into the Objectionable list is that you lose the ability to have any discussion areas where every post is moderated. [Once you enter words into the list, the software will flag only posts containing the moderated words, instead of all posts, for moderated users.] See the moderation section for detailed information. |
(2) The next step is to decide which form fields you want to examine for objectionable words, and then write the macro to look at those. We'll look at Name, Email address, and Second Line. We've checked the HTML source of the existing preferences page to see that the form fields are actually called "name", "email", and "secondline".
|
Note: It would be fairly simple to rework this macro as a Registration Process filter to prevent users from registering with vulgar names or email addresses. However, on the Registration Form the name field is actually called "username". |
%% macro preferencesProcessFilter %%
%% if form( "secondline" ).isObjectionable %%
The second line is not allowed: %% form( "secondline" ).markObjectionable %%
|
This begins the macro in the standard way and then examines the "secondline" field to see if it is objectionable. If it is, it displays a message that informs the user of that fact, and displays the objectionable part in red. If it isn't, it goes on to look at the email field. |
%% else if form( "email" ).isObjectionable %%
That email address is not allowed: %% form( "email" ).markObjectionable %%
%% else if form( "name" ).isObjectionable %%
That name is not allowed: %% form( "name" ).markObjectionable %%
%% endif %%
%% endmacro %%
|
(3) Save this file in your webxTemplates directory as filter.tpl.
(4) In your webx.tpl file, add the following line:
<!--#Include File="filter.tpl"-->
and reset the file cache at Control Panel > Reset file cache.
For further information on macros and the webx.tpl file, see the section on macros.
(5) Now log into you Web Crossing site and go to the Preferences page. Into the second line field, type "poo" and submit the form.
You should see this message appear:
Try the same thing with an email address of "poo@poo.com" or a user name of "poo." You will get the same results.
| Note: Don't worry that you'll accidentally rename the sysop. It's impossible to do from the preferences page, even if something's amiss with your filter and you accidentally slip past it. |
(6) You can go back and change your list of objectionable words at any time to use a list of real vulgarities.
You can do more with filters than just intercept the input and ask the user to go back to the form. You can create a whole new HTML page to send the user to. Perhaps in this case you might want to create a page reminding them of your site's vulgarity policies. Here's how that macro would look:
%% macro preferencesProcessFilter %%
%% if form("secondline").isObjectionable %
<HTML>That second line is not allowed: %% form("secondline").markObjectionable %%
<br><br>
Please read our user policies again. Use the Back button on your browser to go back and try again.</HTML>
%% endif %%
%% endmacro %%
This is
a bare-bones HTML page (you'll want to add title and body tags,
etc.) but you can see what this does, compared to the other method.
It's the <HTML> tag which makes the difference
in how Web Crossing processes the macro, creating a new page or
just an error message on the page you saw earlier.
Try testing it. This is what you should see:
Next Section
The last section will use a powerful feature of WCTL - nested templates - to change the customization of one folder (and its sub-folders), while leaving other folders unchanged.
I tried this example, but my preferences changes go through without anything different happening.
Sysop docs
Web Crossing FAQ
Sysop Control Panel