EXT: Email Address Subscription

Extension Key: sr_email_subscribe

Copyright 2004-2007, Stanislas Rolland / Franz Holzinger <kontakt@fholzinger.com>

This document is published under the Open Content License

available from http://www.opencontent.org/opl.shtml

The content of this document is related to TYPO3

- a GNU/GPL CMS/Framework available from www.typo3.com

Table of Contents

EXT: Email Address Subscription	1

Credits	1

Introduction	3

What does it do?	3

Requirements	3

Support	3

Users manual	4

Subscription Process	4

Invitation	4

Administration	5

Frontend Rendering	5

HTML Template	5

CSS Styles	5

HTML Template Markers	5

Localization	7

Adapting labels	7

Overriding labels specified in TCA	7

Switching salutation mode	8

Labels with variables	8

Adding extra labels	8

Configuration	9

Configuration steps	9

Upgrading to version 1+	9

Extension configuration variables	9

TypoScript Constants	9

TypoScript Setup	10

Configuration FAQ	10

Sending invitations	10

Using frames	10

Reducing the length of URL's	11

Tutorial: Adding fields to the subscription form	12

Extend the tt_address table	12

Add the fields in the HTML template	12

Modify the TS template Constants and Setup	13

Add the language labels for the new fields	13

Using Captcha	14

Known Problems	15

To-Do List	16

Change Log	17

Credits

This extension is derived from the Front End User Admin extension of Kasper Skårhøj.

The email attachment feature is an idea of Volker Graubaum <volker.graubaum(AT)e-netconsulting.de>.

Validation of Internet site url's is based on URL Validator by Esben Maaløe <esm(AT)baseclassmodulweb.dk>.

In order to support dates before 1970, the field “date of birth” is handled with the ADOdb Date Time Library by John Lim.

Thanks to Steve Webster for sharing his code for the short URL feature.

Introduction

What does it do?

The Email Address Subscription extension is an email-based subscription extension, a variant of Kasper Skårhøj's Direct Mail Subscription (direct_mail_subscription).

The Email Address Subscription extension is built as an extension of the Front End User Registration (sr_feuser_register) extension and therefore has very similar features, including:

Use of standard TYPO3 facilities and tools: localization, alternate languages, character sets other than ISO 8859-1, TypoLink URLs, constant editor, default CSS in TypoScript setup;

Use of country codes, country subdivision codes and language codes of the Static Info Tables;

Addition of first name, last name, date of birth;

Compatibility with extension Direct Mail 2.0 in the use of field Receive HTML emails?' (module_sys_dmail_html) and of Direct Mail Categories (module_sys_dmail_category);

Sending HTML emails;

Optional attachment to HTML confirmation emails;

Subscriber upload and maintenance of a set of images (presumably photos);

Validation of the subscriber's Internet site URL;

Sending an invitation to subscribe;

Switching salutation mode;

Optional CSS-styled XHTML 1.0 Strict template;

Optional use of backend flexforms, using extension FE, BE Library (fh_library);

Compatibility with extension Database Abstraction Layer (dbal).

Requirements

This extension requires TYPO3 4.0. If used in conjunction with Direct Mail, then Direct Mail 2.0+ is required.

For Version 1.2.0+ a version 2.5.7+ of the extension Front End User Registration (sr_feuser_register) must be installed.

For Versions < 1.2.0 a version 2.5.0-2.5.5 of the extension Front End User Registration (sr_feuser_register) must be installed. All features will be incorporated into sr_feuser_register 2.5.7+.

The extension also requires the Address List (tt_address) extension 2.1.0+ .

Version 0.2.9 is the last version of this extension that will work with TYPO3 3.6.0-3.8.2. Version 2.2.7 of extension Front End User Registration (sr_feuser_register) should then be used.

Version 0.2.9 is the last version of this extension that will run with TYPO3 3.5.0, provided that the TS setup property config.metaCharset is not used. Version 2.2.7 of extension Front End User Registration (sr_feuser_register) should then be used.

Support

You may get support regarding the use of this extension by subscribing to the English User List: http://typo3.org/documentation/mailing-lists/english-main-list-archive/

You can get support and installation service for this extension at Jambage Forum - Email Reg .

Please see/report problems in the TYPO3 Bugtracker under project tx_srfeuserregister.

Users manual

First, the extension needs to be installed and configured: see the Configuration section.

Second, the HTML template needs to be tailored to your site: see the Administration section.

Then, visitors can start subscribing with their email addresses.

Subscription Process

The default procedure will be as follows:

the visitor is presented a subscription form and, for the case that he may already be subscribed, a link to be used to update or terminate his subscription;

the first time visitor completes the subscription form; on submit, he is presented a preview form, so that he may verify the information before creating his subscription account; he is then informed that an email is being sent to him to complete the subscription process; his subscription account is hidden, preventing any newsletter being sent until the process is completed;

an email is thus sent to the potential subscriber; this message contains two links: one allows the visitor to confirm his subscription, the other to cancel (in case somebody has used his email address);

clicking on either link brings the visitor to a message page displayed in his browser; if he has confirmed his subscription, he is presented a welcome message; when the subscriber confirms his subscription, his subscription account becomes active allowing newsletters to be sent to the subscriber;

if a subscriber wishes to update or terminate his subscription, he follows the link presented for this purpose; he is then requested to enter his email so that a message with appropriate links can be sent to his mailbox;

an email is thus sent to the subscriber; this message contains two links: one brings the subscriber to a page with an update form, the other allows the subscriber to terminate his subscription;

upon each event (subscription, confirmation, cancellation, update or termination), an email may be sent to the subscriber to confirm the action; an email notification may also be sent to the administrator of the site; the email to the subscriber may be in HTML format (the email will always include a plain text version).

Invitation

The extension may also be configured so that an authorized user can create a subscription for a person and send to the person an invitation to confirm her subscription or decline the invitation.

Administration

Frontend Rendering

HTML Template

The default template provided with the plugin depends on which static template you are using: Email Address Subscription CSS-styled or Email Address Subscription Old Style.

When using static template Email Address Subscription CSS-styled, the default template is:

EXT:sr_email_subscribe/pi1/tx_sremailsubscribe_pi1_css_tmpl.html

CSS Styles

Default CSS styles are defined in the default TS template setups. They will vary depending on which static template you are using: Email Address Subscription CSS-styled or Email Address Subscription Old Style.

As usual, the default CSS styles may be modified and moved to a .css file. In such a case , the location of the file should be specified by an import rule overriding the default TS template setup:

plugin.tx_sremailsubscribe_pi1._CSS_DEFAULT_STYLE = @import url("fileadmin/styles/some_style_sheet_file.css");

Alternatively, the selectors may be moved to some site-wide style sheet file and the default styles may be nullified:

plugin.tx_sremailsubscribe_pi1._CSS_DEFAULT_STYLE >

When using static template Email Address Subscription CSS-styled, the following selectors are used in the example HTML template and are defined in default TS setup:

.tx-sremailsubscribe-pi1 p { }

.tx-sremailsubscribe-pi1 p.tx-sremailsubscribe-pi1-click-to-edit { }

.tx-sremailsubscribe-pi1 h4 { }

.tx-sremailsubscribe-pi1 legend { }

.tx-sremailsubscribe-pi1 .tx-sremailsubscribe-pi1-notice { }

.tx-sremailsubscribe-pi1 .tx-sremailsubscribe-pi1-trash { }

.tx-sremailsubscribe-pi1 a { }

.tx-sremailsubscribe-pi1 label { }

.tx-sremailsubscribe-pi1 label span { }

.tx-sremailsubscribe-pi1 .tx-sremailsubscribe-pi1-error { }

.tx-sremailsubscribe-pi1 input { }

.tx-sremailsubscribe-pi1 input[type=password] { }

* html .tx-sremailsubscribe-pi1 input.tx-sremailsubscribe-pi1-password { }

.tx-sremailsubscribe-pi1 input[type=radio], .tx-sremailsubscribe-pi1 input[type=checkbox] { }

* html .tx-sremailsubscribe-pi1 input.tx-sremailsubscribe-pi1-radio, * html .tx-sremailsubscribe-pi1 input.tx-sremailsubscribe-pi1-checkbox { }

.tx-sremailsubscribe-pi1 .tx-sremailsubscribe-pi1-delete-icon { }

.tx-sremailsubscribe-pi1 .tx-sremailsubscribe-pi1-delete-icon:hover { }

.tx-sremailsubscribe-pi1 a.tx-sremailsubscribe-pi1-file-view { }

.tx-sremailsubscribe-pi1 ul { }

.tx-sremailsubscribe-pi1 ul.tx-sremailsubscribe-multiple-checkboxes { }

.tx-sremailsubscribe-pi1 ul.tx-sremailsubscribe-multiple-checkboxes li { }

.tx-sremailsubscribe-pi1 ul.tx-sremailsubscribe-multiple-checkboxes li label { }

.tx-sremailsubscribe-pi1 ul.tx-sremailsubscribe-multiple-checked-values li { }

.tx-sremailsubscribe-pi1 dl { }

.tx-sremailsubscribe-pi1 dt, .tx-sremailsubscribe-pi1 dd { }

.tx-sremailsubscribe-pi1 dt { }

.tx-sremailsubscribe-pi1 dd { }

.tx-sremailsubscribe-pi1 .tx-sremailsubscribe-pi1-multiple-checkboxes dt { }

.tx-sremailsubscribe-pi1 .tx-sremailsubscribe-pi1-multiple-checkboxes dd { }

* html .tx-sremailsubscribe-pi1 dd { }

.tx-sremailsubscribe-pi1 dd p { }

.tx-sremailsubscribe-pi1 dd label { }

HTML Template Markers

The following is the list of global and main subparts markers used in the example HTML template, when using static template Email Address Subscription CSS-styled.

Global markers:

###CHARSET### = config.metaCharset or iso-8859-1

Main subparts markers:

###TEMPLATE_CREATE### : template used to display the initial subscription form.

###TEMPLATE_CREATE_PREVIEW### : template used to display the (optional) subscription preview form.

###TEMPLATE_CREATE_SAVED### : template used to display confirmation that the subscription account was created (when email confirmation request is disabled).

###TEMPLATE_SETFIXED_CREATE### : template used to display confirmation that the subscription account was created but that an email is being sent to the subscriber to complete the subscription process (when email confirmation request is enabled).

###TEMPLATE_INVITE### : template used to display the invitation form.

###TEMPLATE_INVITE_PREVIEW### : template used to display the (recommended) invitation preview form.

###TEMPLATE_SETFIXED_INVITE### : template used to display confirmation that a subscription account was created and that an invitation email has been sent to the potential subscriber to complete the subscription process or decline the invitation.

###TEMPLATE_INFOMAIL### : template used to display a screen that allows the subscriber to request links to be sent to his email address so that he(she) may update or terminate his(her) subscription.

###TEMPLATE_INFOMAIL_SENT### : template used to display confirmation that the “infomail” message is being sent to the subscriber.

###TEMPLATE_EDIT### : template used to display the subscription account editing form.

###TEMPLATE_EDIT_PREVIEW### : template used to display the (optional) editing preview form.

###TEMPLATE_EDIT_SAVED### : template used to display confirmation that the subscription account was updated.

###TEMPLATE_DELETE_PREVIEW### : template used to display the deletion confirmation form.

###TEMPLATE_DELETE_SAVED### : template used to display confirmation that the subscription was terminated.

###TEMPLATE_SETFIXED_OK### : template used to display confirmation that the subscription process was completed.

###TEMPLATE_SETFIXED_OK_DELETE### : template used to display confirmation that the subscription process was canceled.

###TEMPLATE_SETFIXED_FAILED### : template used to display a message when the subscription or cancellation process could not be completed.

###TEMPLATE_AUTH#### : template used to display a link to the subscription form.

###TEMPLATE_NO_PERMISSIONS### : template used to display a message when some illegal access is attempted.

###EMAIL_TEMPLATE_CREATE_SAVED_HTML### : template for the HTML message sent to the subscriber when he has subscribed (when email confirmation request is disabled).

###EMAIL_TEMPLATE_CREATE_SAVED### : template for the plain text message sent to the subscriber when he has subscribed (when email confirmation request is disabled).

###EMAIL_TEMPLATE_CREATE_SAVED_ADMIN### : template for the plain text notification sent to the site administrator when a visitor has subscribed (when email confirmation request is disabled).

###EMAIL_TEMPLATE_EDIT_SAVED_HTML### : template for the HTML message sent to the subscriber when he has updated his subscription account.

###EMAIL_TEMPLATE_EDIT_SAVED### : template for the plain text message sent to the subscriber when he has updated his subscription account.

###EMAIL_TEMPLATE_EDIT_SAVED_ADMIN### : template for the plain text notification sent to the site administrator when a subscriber has updated his subscription account.

###EMAIL_TEMPLATE_SETFIXED_CREATE_HTML### : template for the HTML message sent to the subscriber when he has created a subscription account and need to confirm his subscription (when email confirmation request is enabled).

###EMAIL_TEMPLATE_SETFIXED_CREATE### : template for the plain text message sent to the subscriber when he has created a subscription account and need to confirm his subscription (when email confirmation request is enabled).

###EMAIL_TEMPLATE_SETFIXED_CREATE_ADMIN### : template for the plain text notification sent to the site administrator when a subscriber has created a subscription account and needs to confirm his subscription (when email confirmation request is enabled).

###EMAIL_TEMPLATE_SETFIXED_INVITE_HTML### : template for the HTML invitation message sent to a person for whom a subscription account has been created and requesting accept the invitation to confirm his subscription, or to decline the invitation (or ignore the message).

###EMAIL_TEMPLATE_SETFIXED_INVITE### : template for the plain text invitation message sent to a person for whom a subscription account has been created and requesting accept the invitation to confirm his subscription, or to decline the invitation (or ignore the message).

###EMAIL_TEMPLATE_SETFIXED_INVITE_ADMIN### : template for the plain text notification sent to the site administrator when an invitation to register has been sent and the invited person needs to confirm his(her) subscription.

###EMAIL_TEMPLATE_SETFIXED_APPROVE_HTML### : template for the HTML message sent to the subscriber when he has confirmed his subscription.

###EMAIL_TEMPLATE_SETFIXED_APPROVE### : template for the plain text message sent to the subscriber when he has confirmed his subscription.

###EMAIL_TEMPLATE_SETFIXED_APPROVE_ADMIN### : template for the plain text notification sent to the site administrator when a subscriber has confirmed his subscription.

###EMAIL_TEMPLATE_SETFIXED_DELETE_HTML### : template for the HTML message sent to the subscriber when he has canceled his subscription.

###EMAIL_TEMPLATE_SETFIXED_DELETE### : template for the plain text message sent to the subscriber when he has canceled his subscription.

###EMAIL_TEMPLATE_SETFIXED_DELETE_ADMIN### : template for the plain text notification sent to the site administrator when a subscriber has canceled his subscription.

###EMAIL_TEMPLATE_INFOMAIL_HTML### : template for the HTML message sent to the subscriber when he wants to update or terminate his subscription.

###EMAIL_TEMPLATE_INFOMAIL### : template for the plain text message sent to the subscriber when he wants to update or terminate his subscription.

###EMAIL_TEMPLATE_INFOMAIL_NORECORD_HTML### : template for the HTML message sent to the subscriber when no subscription with his email was found.

###EMAIL_TEMPLATE_INFOMAIL_NORECORD### : template for the plain text message sent to the subscriber when no subscription with his email was found.

###EMAIL_TEMPLATE_DELETE_SAVED_HTML### : template for the HTML message sent to the subscriber when he has terminated his subscription.

###EMAIL_TEMPLATE_DELETE_SAVED### : template for the plain text message sent to the subscriber when he has terminated his subscription.

###EMAIL_TEMPLATE_DELETE_SAVED_ADMIN### : template for the plain text notification sent to the site administrator when a subscriber has terminated his subscription.

Localization

Adapting labels

You may adapt the labels in pi1/locallang.xml to to your needs and languages.

Any label may be overridden by inserting the appropriate assignment in your TS template setup:

plugin.tx_sremailsubscribe_pi1._LOCAL_LANG.languageCode.labelName = overridingValue

You can find the name of the label you want to modify (or translate) by inspecting the extension file pi1/locallang.xml.

Overriding labels specified in TCA

You may also override by the same method labels from other files when they are referenced by the TCA definition of a field (see the tutorial section on Adding fields to the registration form). This is done as follows:

plugin.tx_srfeuserregister_pi1._LOCAL_LANG.languageCode.tableName.fieldName = overridingValue

Switching salutation mode

You may also switch the salutation mode used in these labels when this is relevant for the language being used and when the labels are either available in the pi1/locallang.xml file or provided by TypoScript setup. See the TypoScript Reference section.

Labels with variables

Some labels in pi1/locallang.xml have names starting with 'v_'. In those labels, the following variables may be used:

%1$s : the title of the pid containing the subscriber records created by the plugin;

%2$s : the name of the subscriber;

%3$s : the email address of the subscriber;

%4$s : the first name of the subscriber.

Adding extra labels

Property extraLabels in TS setup may specify a list of extra labels that may be used in the HTML template.

The values of these labels are specified in TS setup with the same type of assignment as when overriding localized labels:

plugin.tx_sremailsubscribe_pi1._LOCAL_LANG.languageCode.extraLabelName = extraLabelValue

Configuration

Configuration steps

These are the steps to configuring the Email Address Subscription plugin:

Install the extension using the Extension Manager. If not yet installed, you will be requested to install extensions Static Info Tables (static_info_tables) and Front End User Registration (sr_feuser_register) 2.5.7 +.

Add one of the following static templates to your TypoScript template: Email Address Subscription CSS-styled or Email Address Subscription Old Style.

Create a System Folder page that will contain the subscriber records created by the plugin. Set the TS template constant pid to the page id of this folder.

Create a page; insert the Email Address Subscription plugin, setting the CODE to CREATE, and the Starting Point to the System Folder that will contain the subscriber records created by the plugin. Set the TS template constant registerPID, confirmPID and editPID to the page id of this page.

If you wish to have confirmation and/or edition on different pages, you may also create a second page, insert the Email Address Subscription plugin, leaving the CODE empty and setting the Starting Point to the System Folder that will contain the subscriber records created by the plugin, and set the TS template constants confirmPID and editPID to the page id of this page.

Decide which fields you want to be included on the subscription form and, among those, which ones you want to be required in order to subscribe; set TS template constants formFields and requiredFields.

Review the constants described below. All these properties may be conveniently edited using the Constant Editor TS template tool. If you do not use the Constant Editor to configure the plugin, please note the possible forms of the constants assignments in the constants section of your TS template: plugin.tx_sremailsubscribe.property = value and plugin.tx_sremailsubscribe_pi1.property = value.

Upgrading to version 1+

When you upgrade from an older version to version 1+, you need to add a static template to your TS template, otherwise the extension will not work.

If you add the Email Address Subscription Old Style static template, the extension should function exactly the same way as version 0.3.1.

If you add the Email Address Subscription CSS-styled static template, you need to re-adapt your HTML template and your CSS styles. You should probably try it first with the default template and the default CSS styles.

Previous to version 1.0.0, the extension contained two plugins. Plugin tx_sremailsubscribe_pi2 was used to provide informal or casual salutation mode. This second tx_sremailsubscribe_pi2 plugin is now DELETED. Switching salutation mode is now configured in the TS template with TS Constant salutation.

Note that this second plugin is now configured only when static template Email Address Subscription Old Style is used. Therefore, if you are upgrading to static template Email Address Subscription CSS-styled, you must update the content elements that refer to plugin tx_sremailsubscribe_pi2. These should be updated to refer to the remaining plugin. Salutation mode should then be set to informal in the TS template.

Extension configuration variables

The Extension Manager installation dialog allows you to set the following extension configuration variable:

Use flexforms: this variable enables the use of Flexforms in the backend. Extension fh_library version 0.0.4+ must be installed. Default is 1.

TypoScript Constants

Constants (plugin.tx_sremailsubscribe)

Please note that the following properties refer to TS template constants, not TS template setup.

If you do not use the Constant Editor to configure the plugin, please note the form of the constants assignments in the constants section of your TS template: plugin.tx_sremailsubscribe.property = value

See the manual of sr_feuser_register.

Constants (plugin.tx_sremailsubscribe_pi1)

Please note that the following properties refer to TS template constants, not TS template setup.

If you do not use the Constant Editor to configure the plugin, please note the form of the constants assignments in the constants section of your TS template: plugin.tx_sremailsubscribe_pi1.property = value

Property:	Data type:	Description:	Default:
file.attachmentFile	string	File name of a file to be attached to the subscription confirmation email.	EXT:sr_email_subscribe/pi1/tx_sremailsubscribe_pi1_sample.txt
HTMLMailCSS	string	File name of the HTML emails style sheet. If HTML emails are enabled, this file contains the CSS style sheet to be incorporated in these emails.	EXT:sr_email_subscribe/pi1/tx_sremailsubscribe_htmlmail.css

TypoScript Setup

When installing this extension, you should NOT use the following setting:

config.disableAllHeaderCode = 1

This setting will prevent the inclusion of Javascript essential to the correct behavior of the profile editing features.

Property:	Data type:	Description:	Default:
extraLabels	string	Comma-separated list of additional labels to use in the HTML template. See section Labels and localization about adding extra labels.	None

Configuration FAQ

Sending invitations

Create a page, limiting access to this page to users who will be authorized to send invitations to subscribe. Insert the one of the Email Address Subscription plugins, setting the CODE to INVITE, and the Starting Point to the System Folder that will contain the subscriber records created by the plugin.

When a subscription account is created through this page, an invitation message is sent to the email address specified on the subscription account. The invited person may accept or decline the invitation.

Using frames

If the subscription confirmation et edition pages (confirmPID and editPID) are designed to be displayed within frames, then you should add the following lines to your TS template setup:

[globalVar = TSFE:id = {$plugin.tx_sremailsubscribe.confirmPID}, TSFE:id = {$plugin.tx_sremailsubscribe.editPID} ]

config.page.frameReloadIfNotInFrameset = 1

config.linkVars >

config.linkVars = L,tx_sremailsubscribe_pi1,fD,cmd,rU,aC

config.no_cache = 1

[global]

after setting plugin.tx_sremailsubscribe.confirmPID and plugin.tx_sremailsubscribe.editPID in your TS template constants.

Note that cmd, rU and aC are in the list for compatibility with the Direct mail extension.

Reducing the length of URL's

You may find that the url's sent in emails to the subscriber are too long and may be broken when using plaintext emails.

Using HTML emails and simulateStaticDocuments

If you are using HTML emails (enableHTMLMail is set to 1):

Configure your site to use the simulateStaticDocuments property. See TSRef for information about this CONFIG setup property.

When the simulateStaticDocuments is working, then add the following lines to your TS template setup:

config.simulateStaticDocuments_pEnc = md5

config.simulateStaticDocuments_pEnc_onlyP = L,fD[_FIELDLIST],fD[hidden],tx_sremailsubscribe_pi1[aC], tx_sremailsubscribe_pi1[cmd],tx_sremailsubscribe_pi1[rU],tx_sremailsubscribe_pi1[sFK]

Using plain text emails and notification_email_urlmode

If you are using plaintext emails (enableHTMLMail is set to 0), the above method will also work, but if you do not wish to use the simulateStaticDocuments feature, then:

In your TS template setup, set config.notification_email_urlmode = 76 or config.notification_email_urlmode = all . See TSRef for information about this CONFIG setup property.

Using the short URL feature, possibly with RealURL

This approach is compatible with both HTML and plain text emails. Simply enable the feature by setting the TS constant useShortUrls = 1 in your TS template. You should also review the default value of TS constant shortUrlLife and set it to a value that fits your needs.

If you are using the simulateStaticDocuments feature, you may want to add tx_sremailsubscribe_pi1[regHash] to the list simulateStaticDocuments_pEnc_onlyP.

If you are using the RealURL extension, you should add something like the following to your RealURL configuration in the $TYPO3_CONF_VARS['EXTCONF']['realurl'] variable of localconf.php:

'postVarSets' => array(

'_DEFAULT' => array(

'subscribe' => array(

array(

'GETvar' => 'tx_sremailsubscribe_pi1[regHash]'

)

)

),

Tutorial: Adding fields to the subscription form

Extend the tt_address table

The simplest way to extend the tt_address table is to create a small extension that will define the required fields in the database and the TCA. Your small extension will not contain any plugin or other processing.

The extension Extension Repository Kickstarter is a wizard that will help you create this small extension. If not yet installed, install the extension Extension Repository Kickstarter (extension key extrep_wizard) using the Extension Manager. Once installed, you access the Kickstarter Wizard through the Extension Manager back end module. There is a tutorial on how to use the Kickstarter Wizard to create a small extension. You may want to go through it. Just remember that you will not need to create any plugin or TypoScript.

Once your extension is created, install it. This will make the fields you have defined available to all other extensions.

Add the fields in the HTML template

You need to update the HTML template in order to include in the proper subparts the fields you have defined. The subparts of interest are:

###TEMPLATE_CREATE###

###TEMPLATE_CREATE_PREVIEW###

###TEMPLATE_INVITE###

###TEMPLATE_INVITE_PREVIEW###

###TEMPLATE_EDIT###

###TEMPLATE_EDIT_PREVIEW###

and perhaps some of the email subparts.

Have a look at how the pre-defined fields are included in each of the subparts, and do the same for the fields you are adding.

The HTML for a field named myNewFieldName in the CREATE, INVITE and EDIT subparts would look like:

<!-- ###SUB_INCLUDED_FIELD_myNewFieldName### -->

<dt>

<label for="tx-sremailsubscribe-pi1-myNewFieldName">###LABEL_MYNEWFIELDNAME###</label>

<span class="tx-sremailsubscribe-pi1-required">###REQUIRED_MYNEWFIELDNAME###</span>

</dt>

<dd>

<!-- ###SUB_ERROR_FIELD_myNewFieldName### -->

<p class="tx-sremailsubscribe-pi1-error">###EVAL_ERROR_FIELD_myNewFieldName###</p>

<!-- ###SUB_ERROR_FIELD_myNewFieldName### -->

<!-- ###SUB_REQUIRED_FIELD_myNewFieldName### -->

<p class="tx-sremailsubscribe-pi1-error">###MISSING_MYNEWFIELDNAME###</p>

<!-- ###SUB_REQUIRED_FIELD_myNewFieldName### -->

<input id="tx-sremailsubscribe-pi1-myNewFieldName" type="text" size="40" maxlength="50" title="###TOOLTIP_MYNEWFIELDNAME###" name="FE[tt_address][myNewFieldName]" class="tx-sremailsubscribe-pi1-text" />

</dd>

<!-- ###SUB_INCLUDED_FIELD_myNewFieldName### -->

In the case of a field of type textarea, check, radio and select, the HTML for the field should rather look like the following:

<!-- ###SUB_INCLUDED_FIELD_myNewFieldName### -->

<dt>

<label for="tx-sremailsubscribe-pi1-myNewFieldName">###LABEL_MYNEWFIELDNAME###</label>

<span class="tx-sremailsubscribe-pi1-required">###REQUIRED_MYNEWFIELDNAME###</span>

</dt>

<dd>

<!-- ###SUB_ERROR_FIELD_myNewFieldName### -->

<p class="tx-sremailsubscribe-pi1-error">###EVAL_ERROR_FIELD_myNewFieldName###</p>

<!-- ###SUB_ERROR_FIELD_myNewFieldName### -->

<!-- ###SUB_REQUIRED_FIELD_myNewFieldName### -->

<p class="tx-sremailsubscribe-pi1-error">###MISSING_MYNEWFIELDNAME###</p>

<!-- ###SUB_REQUIRED_FIELD_myNewFieldName### -->

###TCA_INPUT_myNewFieldName####

</dd>

<!-- ###SUB_INCLUDED_FIELD_myNewFieldName### -->

In each PREVIEW subpart, you need to add lines like:

<!-- ###SUB_INCLUDED_FIELD_myNewFieldName### -->

<dt>###LABEL_MYNEWFIELDNAME###</dt>

<dd>###FIELD_MYNEWFIELDNAME###</dd>

<!-- ###SUB_INCLUDED_FIELD_myNewFieldName### -->

or

<!-- ###SUB_INCLUDED_FIELD_myNewFieldName### -->

<dt>###LABEL_MYNEWFIELDNAME###</dt>

<dd>######TCA_INPUT_MYNEWFIELDNAME###</dd>

<!-- ###SUB_INCLUDED_FIELD_myNewFieldName### -->

Modify the TS template Constants and Setup

Using the Constant Editor, modify the value of the following constants of plugin tx_sremailsubscribe:

formFields: add to the list of fields the names of the fields that you have defined and that you want to be displayed in the front end subscription form; if the field is not in this list the subpart

<!--###SUB_INCLUDED_FIELD_myNewFieldName###--> will be deleted;

requiredFields: add to the list of fields the names of the fields that you have defined and that you want to be treated as required fields; if the field is not in the list OR if the field is in this list and is correctly filled, the subpart

<!--###SUB_REQUIRED_FIELD_myNewFieldName###--> will be deleted.

You may also specify in the TS template Setup some default values and validation rules to be applied by the extension to the additional fields.

If there are no validation rules, you should set:

plugin.tx_sremailsubscribe_pi1.create.evalValues.myNewFieldName =

If your field is a select field and if you wish to enable multiple selection, you should also set:

plugin.tx_sremailsubscribe_pi1.parseValues.myNewFieldName = multiple

Add the language labels for the new fields

The language labels for the additional database fields should be added in Step1 above. These will be used by the back end forms.

The language labels used by the front end plugin should be added in the TS template setup using the method described in section Localization of this document. For each language of interest to you with languageCode , you may need the following statements for each additional field with myNewFieldName:

the basic field label:

plugin.tx_sremailsubscribe_pi1._LOCAL_LANG.languageCode.f myNewFieldName = myNewFieldLabel

the message displayed when the field is required but missing:

plugin.tx_sremailsubscribe_pi1._LOCAL_LANG.languageCode.missing_myNewFieldName = missingRequiredFieldMessage

same as previous but for the invitation form:

plugin.tx_sremailsubscribe_pi1._LOCAL_LANG.languageCode.missing_invitation_ myNewFieldName = missingRequiredFieldMessageOnInvitationForm

the message displayed when a validation rule evalRuleName applicable to the field is not satisfied:

plugin.tx_sremailsubscribe_pi1._LOCAL_LANG.languageCode.evalErrors_evalRuleName_myNewFieldName = errorMessageForEvalRule

Using Captcha

It is possible to activate the display of a captcha image and a text field, where the user must enter the text displayed on the image. sr_freecap must have been installed. See the tx_sremailsubscribe_pi1_captcha_css_tmpl.html example template.

Example Constants

formFields = email,first_name,last_name,captcha_response,module_sys_dmail_html

Example Setup:

# check for captcha

plugin.tx_sremailsubscribe_pi1.create.evalValues.captcha_response = captcha

plugin.tx_sremailsubscribe_pi1._CSS_DEFAULT_STYLE >

plugin.tx_sremailsubscribe._CSS_DEFAULT_STYLE >

plugin.tx_srfreecap_pi2._CSS_DEFAULT_STYLE >

Known Problems

Although the subscriber may enter a date of birth before 1970, the date cannot be edited on the back end form, as Typo3 does not provide support for such dates.

Please see/report problems in the TYPO3 Bugtracker under project tx_srfeuserregister.

To-Do List

A number of useful features could be added to this extension. Some of these features are listed below. If you have developed such enhancements and would like them to be integrated to the base extension, or if you would be interested in sponsoring any such enhancements, please contact the author.

Possible feature enhancements:

offer an administrative approval process before subscription is enabled;

use SMTP to send emails.

Change Log

Version:	Changes:
0.1.0	Initial public release.
0.2.1	Finnish and partial Dutch translations. Thanks to the translators.
0.2.3	Correction to the locallang files. The field telephone is named phone in tt_address. Updated Finnish translation.
0.2.4	Addition of module_sys_dmail_category field in HTML template with allowance for 10 categories. Addition of dmailCategories TypoScript constant. Requires version 1.3.5+ of extension Front End User Registration (sr_feuser_register).
0.2.5	Update to Danish, Finnish and Norwegian translations.
0.2.6	Documentation change: see TypoScript constant enableEmailOnRefuse.
0.2.7	Correction when used with version 1.6.2+ of extension Front End User registration (key: sr_feuser_register): local validation of email duplicates did not work. Thanks to Armin Günther for this correction. New TS Constant pidTitleOverride when used with version 1.6.2+ of extension Front End User registration (key: sr_feuser_register): allows to override the title of the System Folder containing the email addresses records when the title is used in some online and/or email messages.
0.2.8	Update to the German translation. Thanks to Andreas Flügge.
0.2.9	Add first name of subscriber to the list of variables that may be used in labels. Correction: Take into account the preference of the subscriber when sending plain or HTML emails. Requires version 0.6.8+ of sr_feuser_register extension. New TS Constants: confirmInvitationPID and infomailPID. A few new labels.
0.3.0	Remove changes to the TCA for columns module_sys_dmail_category and module_sys_dmail_html of tt_address table. Ignore fields module_sys_dmail_category and module_sys_dmail_html if direct_mail extension is not installed. Enable support for select fields with MM relations, in particular module_sys_dmail_category, including localization when configured on the foreign table. Modify the HTML template to make field module_sys_dmail_category TCA-driven and use dynamic categories introduced by extension Direct Mail (direct_mail) 2.0. Add constant and setup property module_sys_dmail_category_PIDLIST Accept value '0' on required fields (see bugtracker issue #2027). Honor TCA default value for TCA-driven multiple checkboxes. Thanks to Simon Tuck. Remove support for TYPO3 3.5.0. Add short URL's feature and TS constants useShortUrls and shortUrlLife. Thanks to Steve Webster. Modify plugins initialization and add class constructors. If used with Direct Mail, then TYPO3 4.0 and Direct Mail 2.0 are required.
0.3.1	Remove TS constants enableInfomail, enableAdminNotifyOnRefuse, enableEmailOnRefuse
1.0.0	Remove TS constants dmailCategories. Enable the optional use of flexforms in the backend. Thanks to Franz Holzinger. New extension configuration variable. Two TS Static Templates: Email Address Subscription CSS-styled and Email Address SubscriptionOld Style, and modified installation instructions. New xhtml css-styled template. Merge the two previously defined plugins into one and use TS template to configure salutation mode. Convert all language files to xml format.
1.1.0	Remove dependency on Static Info Library (sr_static_info). Now requires Static Info Tables 2.0.0+
1.1.1	Add Slovenian translation.
1.1.2	Add Captcha template for sr_feuser_register 2.5.5
1.2.0	This will work with sr_feuser_register 2.5.7+

EXT: Email Address Subscription - 17

EXT: Email Address Subscription

Kasper Skårhøj

2002-11-01T00:32:00

Kasper Skårhøj