DEPRECATION WARNING

This documentation is not using the current rendering mechanism and is probably outdated. The extension maintainer should switch to the new system. Details on how to use the rendering mechanism can be found here.

Administrator Manual¶

Installation¶

This extension depends on both wt_spamshield and formhandler extensions. Thus you need to install them before installing wt_spamshield_formhandler.

You need to install static templates from both wt_spamshield and wt_spamshield_formhandler. wt_spamshield static template should be loaded before wt_spamshield_formhandler static template.

Configuration¶

All the configuration is performed using TypoScript. There are global options you can configure for all forms, and there are options you can configure for specific form. Global options are accessible through setup and constants of wt_spamshield, while local options are configurable on the TypoScript of the form. Local options always override global options.

Because of the versatility of formhandler, wt_spamshield protection is not automatically enabled, but need to be configured on each form.

Global options¶

Configuration options described here are specific to wt_spamshield_formhandler. Please referer to wt_spamshield manual for other configuration options.

TypoScript constants¶

All the constants are configurable using constant editor, under WT_SPAMSHIELD MAIN category.

plugin.wt_spamshield.formhandler: If false, wt_spamshield protection is disabled for all forms (default: true)
plugin.wt_spamshield.validators.formhandler.enable: Comma separated list of enabled validators. Can be: blacklistCheck, httpCheck, uniqueCheck, honeypotCheck, akismetCheck. By default, all validators are enabled.
plugin.wt_spamshield.formhandler.how_many_validators_can_fail: Number of tests that can fail before reporting the form as spam. For example, if it is 1, there must be at least 2 checks that fail to report the form as spam. Default: 0.
plugin.wt_spamshield.honeypot.inputname.formhandler: Name of the field used for the honeypot. Default: uid987651.

TypoScript setup¶

plugin.wt_spamshield.fields.formhandler: Default names of the form fields used for Akismet check. See Akismet configuration details below for more information.

Formhandler Interceptor configuration¶

In order to enable wt_spamshield protection on a formhandler form, you need to configure a Save Interceptor in the form TypoScript configuration. Here is an example:

plugin.Tx_Formhandler.settings {
    ...
    saveInterceptors {
        1.class = Tx_WtSpamshieldFormhandler_Interceptor_WtSpamshield
        1.disable = 0
        1.config {
            redirectPage = 100
            loggers {
                1.class = Logger_DB
            }
            akismetCheck.fields {
                author = name
                email = email
                homepage =
                body = message
                permalink =
            }
            httpCheck.maximumLinkAmount = 1
            uniqueCheck.fields = name,email
        }
    }
}

The only mandatory configuration option is the class, since it tells formhandler to use the WtSpamshield Interceptor. All the configuration options for the interceptor go inside the config sections. There are two kinds of options: those who configure the formhandler interceptor, and those who configure the spamshield protection.

Interceptor configuration options¶

You should at least configure either redirectPage or templateFile.

redirectPage: Page id or url where to redirect user, if spam is detected. If configured, the user will be redirected to this page if the spam check fail.
correctRedirectUrl: Replaces '&' with '&' in URL
additionalParams: Adds additional parameters to the redirect URL. Each parameter can be a string or a TypoScript object.
headerStatusCode: Set a custom header code set when redirecting to another page.
templateFile: Path to template file or template code to display if spam check fail.
loggers: You can configure formhandler loggers here, to log data when spam is detected. Otherwise, form data is discarded. See formhandler Logger documentation for more details. If you enable Loggers, you should consider disabling the logging already performed by wt_spamshield; otherwise you will log spam twice.
validators.enable: Comma separated list of validators to use. Override the global option. Use this if you want to enable or disable some specific validators for this form. Possible validators are: blacklistCheck, httpCheck, uniqueCheck, honeypotCheck, akismetCheck.
validators.how_many_validators_can_fail: Use this to override the default number of validators that can fail, for this specific form.

Blacklist configuration¶

To blacklist email of IP addresses, the only thing you need to do is to add some spamshield blacklist records somewhere. Off course, blacklistCheck must be in the list of enabled validators.

HTTP configuration¶

This validator counts the total number of links present in all fields of the form. If this number is greater than maximumLinkAmount (default is 3), the form is reported as spam. The definition of links is everything than contains http://, https://, or ftp.

httpCheck.maximumLinkAmount: Number of links allowed in the form.

Unique configuration¶

This validator ensure that given fields does not contain the same value. You can specify different groups of fields to check for uniqueness.

uniqueCheck.fields: Each field are separated by a comma. Each independent groups of fields are separated by a semi-column. For instance, if uniqueCheck.fields = firstname,lastname;field1,field2,field3 , firstname and lastname must be different, as well as any value in field1, field2, and field3, but firstname and field1 could be the same value.

Honeypot configuration¶

The principle of the honeypot is to add a field that is not visible to the user, but is visible to bots. If there is any value filled into the honeypot field, the form is reported as spam.

honeypotCheck.inputname: The name of the input used for the honeypot check. You must ensure there is a field with this name somewhere in the form.

To include the honeypot field into the form, you can simply add the ###HONEYPOT### marker at the beginning of you form template. This marker is defined in plugin.Tx_Formhandler.settings.markers.HONEYPOT TypoScript object. Most of the parameters of this field can be configured using TypoScript constants of wt_spamshield. If you locally change the value of honeypotCheck.inputname and you use the ###HONEYPOT### marker, you must modify it to reflect the change. It can be done by putting something like

markers.HONEYPOT < plugin.Tx_Formhandler.settings.markers.HONEYPOT
markers.HONEYPOT.value < plugin.Tx_Formhandler.settings.saveInterceptors.1.config.honeypotCheck.inputname

in you form TypoScript configuration. If you defined a custom formValuePrefix in you form, you should also modify the HONEYPOT marker like:

markers.HONEYPOT.value.prepend.value < .formValuesPrefix

Instead of using the HONEYPOT marker, it is also possible to manually add the honeypot field to your form. In that case, be sure to use the same name for the input as you defined in honeypotCheck.inputname, and be sure to use the right styles to hide the honeypot field in the form.

Akismet configuration¶

The first thing you need is to configure your Akismet key. You must register on akismet to get a key. Then, you must enter you key in the plugin.wt_spamshield.akismetCheck.akismetKey TypoScript constant of wt_spamshield.

The most fields you use, the most precise the check will be. Unused fields can be left blank.

akismetCheck.fields.author: Field to use as author name
akismetCheck.fields.email: Field to use as author email
akismetCheck.fields.homepage: Field to use as author web page
akismetCheck.fields.body: Field to use as the body of the comment or the message
akismetCheck.fields.permalink: Field to use as the permalink for the entered comment