|
WCTL
Server-side Scripting
Using
Process Filters
Introduction
Creating a Preferences Process Filter
Sending to a New HTML Page
Troubleshooting
Resources
Next Section
Introduction
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:
- authentication
- login
- login
failure
- registration
- registration
failure
- preferences
processing
- HTTP
basic login failure
- and
for before and after adding or editing of Folders,
Discussions,
Messages, Links, or Chat Rooms
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 %%
- The
rest of the macro examines the email and name fields in
the same way.
- If
none of the "if" statements are
true, the macro
does nothing - just as if it weren't there.
|
(3) Save this file in your webx 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.
Sending
to A New HTML Page
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
%%
<P>
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.
Troubleshooting
I tried
this example, but my preferences changes go through
without anything
different happening.
- Make
sure you have templates turned on (at the bottom of
the Control
Panel). Also make sure that
filter.tpl is inside
the Web Crossing folder and that you changed
webx.tpl
to include it, or that you've placed it directly in
the webx.tpl
file itself.
- Make
sure you have an objectionable word listed in the
Control
Panel > Customizing > General Settings > Moderated
Posts and that at least one of your words is
in the form
fields you're checking for in the macro.
- Make
sure you reset your file cache.
Resources
Sysop
docs
Web Crossing
FAQ
Sysop
Control Panel
- Reset
File Cache
- Customizing
WCTL
Concept Reference Page
Web
Crossing Tech Support Forum
Developer
Center
WebX
Harbor
|
