EXT: Formhandler Subscription¶

What does it do?¶

The formhandler_subscription extension provides additional utilities (Finishers, PreProcessors) for the formhandler extension. With these utilites you can build a complete (newsletter) subscription system that includes the subscription itself and updating or deleting a subscription.

Screenshots¶

This is the default registration form that is included in the extension:

Users manual ------------

The first step, to get this extension up and running is importing it in the extension manager and creating the required database tables. Since it is based on the formhandler extension you will need to import and install it as a requirement.

The second step is to include the static TypoScript setup of the extension in your template:

To create the page structure that is needed for the registration process you can import one of the t3d files that you can find in Resources/T3D/pagestructure-XX.t3d. At the moment there are only two languages available, english (en) and german (de).

Now you need to create a sysfolder where you would like to store your subscriber records. You can use any table you like. By default the tt_address table is used. If you want to use tt_address records you will need to install the tt_addressextension.

The last step is setting up the required constants for the extension. If you use the constant editor you should get all information you need.

The most important settings are the IDs of the different pages you created by importing the t3d file:

Available Formhander configurations¶

This is a short overview of the available predefined Formhander configurations:

Edit configuration¶

The extension is fully configured via TypoScript. The configuration options that are available can be found on the Formhandler homepage and in the Configuration section of this document.

Edit language labels¶

To overwrite or add language labels you will need two things:

Create a language file in the TYPO3 Locallang XML format

Add this Locallang file to the configuration of formhandler

This is a short example of a Locallang file:

<?xml version="1.0" encoding="utf-8" standalone="yes" ?>
<T3locallang>
        <data type="array">
                <languageKey index="default" type="array">
                        <label index="legend_email">E-mail address</label>
                </languageKey>
        </data>
</T3locallang>

You can find the Locallang file that is used for the default configuration in Resources/Language/Global.xml.

You need to add you own file (let's assume you put it in fileadmin/formhandler_subscription_lang.xml) to the configuration of the form(s) where you want add or overwrite labels:

plugin.Tx_Formhandler.settings.predef {
        formhandler_subscription_request_subscription {
                langFile.2 = fileadmin/formhandler_subscription_lang.xm
        }
}

If you do not want to use the default Locallang file that comes with this extension, you can use langFile.1instead of langFile.2. Then the default lang file will not be loaded any more.

This is a short overview of the available TypoScript configuration keys of the different forms:

formhandler_subscription_request_subscription

formhandler_subscription_confirm_subscription

formhandler_subscription_request_update

formhandler_subscription_update_subscription

formhandler_subscription_remove_subscription

Global options¶

These options are set in the global section of the form configuration and are not connected to a finisher, pre-processor etc.

Finisher_GenerateAuthCodeDB¶

This finisher is based on the Finisher_GenerateAuthCodeof the Formhandler extension. The big difference is: the generated auth code is totally random (not only based on the referenced record data), it is stored in the database (in the tx_formhandler_subscription_authcodestable) and it is only valid for one day by default. Additionally the generated code can be used for two purposes: unhiding a record or accessing a form.

These are the settings that are relevant to the finisher:

Finisher_InvalidateAuthCodeDB¶

This finisher is very basic. It simply invalidates the submitted auth code by removing it from the database, the session, and the GP array. Additionally, all auth codes referencing the same database record will be removed from the database.

Important! Please make sure that you call PreProcessor_ValidateAuthCodeDBbefore using this finisher. Additionally, the generated auth code has to be generated with the accessFormaction. Otherwise an exception will be thrown if no auth code was submitted or the submitted auth code was invalid.

Finisher_RemoveAuthCodeRecord¶

This finisher deletes the referenced record from the database. It has only one configuration option.

Finisher_Subscribe¶

This finisher does two things.

it checks, if the submitted e-mail address (or whatever you want to use as a key, but e-mail probably makes the most sense) already is a subscriber or not, and if the subscriber is confirmed or not

According to the result of the check more finishers are called (I call them sub-finishers)

And this is how you can configure it:

Finisher_UpdateMmData¶

This finisher does two things.

This finisher can be used to update data in a many-to-many relationship in a MM table.

There is one limitation: The data you want to insert into the table must not be submitted within an array. So if your prefix for your form fields is myform, the name of your select field or your checkboxes needs to be something like myform[myfield][]. It is not possible to introduce another array like myform[myarray][myfield][].

Finisher_ValidateAuthCodeUID¶

This finisher checks, if the uid that was submitted by the form matches the uid of the record that was referenced by the currently available auth code.

This can be used to make sure that the person filling out the update form only can update his or her own record but not the record of other people by manipulating a hidden field in the form.

You have to make sure, that the uid that should be validated is submitted in a (hidden) form field. The name of the field either has to have the same name as the uid field that was used to create the auth code (see setting uidFieldof the Finisher_GenerateAuthCodeDB) or you need to read the UID value by using the compareUidsetting.

Important! Like for the Finisher_InvalidateAuthCodeDB you will have to use the PreProcessor_ValidateAuthCodeDBand you need to generate the auth code with the accessFormaction.

View_AuthCodeMail¶

This view is based on Tx_Formhandler_View_Mail. It works basically exactly like it's parent. But there is one little difference. The auth code stored URL stored in the marker ###value_authCodeUrl###is parsed by htmlspecialchars(). This is quite unhandy when you want to send plain text e-mails (which this extension does by default).

So there is a new marker available that can be used in the plain text mails that has no encoded html characters. This marker is called ###value_authCodeUrlPlain###.

PreProcessor_ValidateAuthCodeDB¶

This pre-processor works similar to the Tx_Formhandler_PreProcessor_ValidateAuthCode, but of course there are some differences and enhancements.

First of all, it validates the submitted auth code against the auth codes stored in the database (in the tx_formhandler_subscription_authcodestable). Additionally, only auth codes that are not older than one day (this threshold can be configured in the global configuration option authCodeDBExpiryTime) are considered to be valid. Last but not least: auth codes that are invalid already are removed from the database. This can be switched off by the global configuration option authCodeDBAutoDeleteExpired.

Like is parent class two pages can be configured: one where the user will be redirected to, if the auth code is valid (redirectPage), and one where the user will be redirected to if the auth code is invalid (errorRedirectPage).

If the auth code is correct the configured action will be executed. After that, the user will be redirected if the pre-processor was configured to do so.

There are two possible actions at the moment: enableRecord and accessForm: