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.

email4download

Author:Kasper Skårhøj
Created:2002-11-01T00:32:00
Changed by:Alex Kellner
Changed:2009-07-13T13:29:08
Author:Alex Kellner
Email:Alexander.Kellner@einpraegsam.net
Info 3:
Info 4:

email4download

Extension Key: wt_email4download

Copyright 2005-2009,

Alex Kellner,

<Alexander.Kellner@einpraegsam.net>

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

email4download 1

wt_email4download introduction 2

What does it do? 2

Feature list 2

Needed third party extensions 2

Screenshots 3

How to use 5

Step by step: 5

Settings 6

Settings in the extension manager 6

Settings in the backend module 7

Typoscript settings 9

FAQ 14

No form is shown if I click an link 14

How can I use my own design for the form 14

There is an XML error if I use Internet Explorer and send some values within the form 14

How to increase the session time 14

Todos 15

Changelog 16

Additional links 17

wt_email4download introduction

What does it do?

If you don't want to give your pdf away for free, you could ask for the user email (to use it for your sales marketing or write some newsletter or to enable a fe_user protected page) before download.

The form asks the user for his email, lastname and firstname before the download could be finished.

The form process will be done in a div layer (looks like a popup) and the values will be parsed by AJAX.

A new backend module will help you and the editors to easily select some files which should be transformed.

Feature list

  • Form process via AJAX
  • User values could be send to an extern target via POST (e.g. to store it in your CRM tool like salesforce)
  • User values could create a new fe_user
  • If the user enters his values one time, he don't have to enter it a second time (value saved in session)
  • You can log in the user as feuser after download (for more donloads e.g.)
  • A new backend module will help to select some files which should be transformed
  • Transformation of the links could be done via Typoscript

Needed third party extensions

  • wt_doorman to save the user values
  • xajax to enable AJAX features
  • TYPO3 4.2.5 needed

Screenshots

Frontend example 1

img-1

Frontend example 2 (wrong email)

img-2

Backend example

img-3

Function diagram

img-4

How to use

Step by step:

  • Ensure that you use TYPO3 3.4.5 or newer
  • Import wt_doorman from TER
  • Import xajax from TER
  • Import wt_email4download from TER
  • Make your settings in the Extension Manager and click update (details see below)
  • IMPORTANT: Add the static template (Add default JS+CSS)
  • Enter a new subpart to your HTML Template called <!-- ###EMAIL4DOWNLOAD### -->
  • Upload a new file (e.g. a PDF)
  • Go into the backend plugin, search the file and check the checkbox (form)
  • Add the new file on any page in the RTE (as you have done it many times before)
  • That's all (see typoscript part below for all settings)

Settings

Settings in the extension manager

Screenshot

img-5

Explanation

This settings are only for the backend module

Name

a

Name

b

Explanation

c

Default value

savePID

a

savePID

b

PID where to save entries: File relations will be saved in PID 0 - but you can define the PID as you want

c

0

fileExtensions

a

fileExtensions

b

Define file extensions: You can define which files should be listed in the backend module (empty for all files, dont use space in your seettings, e.g. pdf,jpg,gif)

c

pdf

showColumns

a

showColumns

b

Define columns to show: Remove not needed columns for backendview (e.g. filename, form, pid) – you can accellerate the view if you disable pid and uid

c

symbol, filename, form, redirect, redirect_text1, redirect_text2, pid, uid

splitFilename

a

splitFilename

b

Break in filenames: If filenames are to long to show, just use this function to break the filename after X letters (e.g. 20)

c

20

Settings in the backend module

Selected mode: file selection
Screenshot
img-6
Explanation

Choose a folder with some files

Name

a

Name

b

Function

c

Additional information

Icon

a

Icon

b

This icon shows you the file extension of the listed file

c

Filename

a

Filename

b

This is the current filename. Clicking on the filename opens file.

c

Break after X signs can be defined in the extension manager

Form

a

Form

b

If you want to activate the form in Frontend (get email from user), check this checkbox

c

If you choose form and redirect, both processes will work

Redirect

a

Redirect

b

If you have a page where you log every download and you have to make a redirection to the page, you can use the additional function redirect

c

Example redirect:

Old: fileadmin/file.pdf

New: index.php?id=1&file=fileadmin/file.pdf&cat=value

Redirect is only a optional feature and could be empty

Redirect String (Cat)

a

Redirect String (Cat)

b

See Redirect: You can enter a category for the current file

c

With category and value you can log your file downloads in a flexible way

Redirect String (Value)

a

Redirect String (Value)

b

See Redirect: You can enter a value for the current file

c

With category and value you can log your file downloads in a flexible way

Used in page (PID)

a

Used in page (PID)

b

All page ID's will be shown on which page the listed file was included

c

IMPORTANT: To accelerate the page generating, you can disable this column in the extension manager

Used in content (UID)

a

Used in content (UID)

b

All tt_content UID's will be shown on which content the listed file was included

c

IMPORTANT: To accelerate the page generating, you can disable this column in the extension manager

Selected mode: export
Screenshot

img-7

Explanation

If you want to export your settings of the current folder, you can click Excel Export to generate an Excel file.

Typoscript settings

Setup
Code from ext_typoscript_setup.txt (in the extension folder)
# WT_EMAIL4DOWNLOAD PLUGIN #

# activate or deactivate the whole plugin in FE
plugin.tx_wtemail4download_pi1._enable = 1

plugin.tx_wtemail4download_pi1 {

        # Constants (see constants for an explanation)
        template = {$plugin.wtemail4download.template}
        template_email = {$plugin.wtemail4download.template_email}
        enable = {$plugin.wtemail4download.enable}
        pid_feuser = {$plugin.wtemail4download.pid_feuser}
        pid_agb = {$plugin.wtemail4download.pid_agb}
        session = {$plugin.wtemail4download.session}
        sendEmailOnRegister = {$plugin.wtemail4download.sendEmailOnRegister}
        feuser.disable = {$plugin.wtemail4download.feuser.disable}
        feuser.login = {$plugin.wtemail4download.feuser.login}
        feuser.password = {$plugin.wtemail4download.feuser.password}
        feuser.usergroup = {$plugin.wtemail4download.feuser.usergroup}
        enable4networkusers = {$plugin.wtemail4download.enable4networkusers}
        disable4referer = {$plugin.wtemail4download.disable4referer}
        disable4usergroup = {$plugin.wtemail4download.disable4usergroup}
        enable4IP = {$plugin.wtemail4download.enable4IP}


        # Using form with typoscript
                # .field enables: path, file, file_redirect, file_hash, form, redirect, redirect_string, redirect_string2, crdate, action
        form = COA
        form {

                # Unhide DIV Layer
                10 = TEXT
                10.value = #
                10.wrap = |" onclick="e4d_toggleMe('email4download');

                # Fill hidden field with filename
                20 = TEXT
                20.wrap = if (document.getElementById('email4download_file') != undefined) document.getElementById('email4download_file').value = '|';
                20.field = path

                # Fill hidden field with redirection path
                30 = TEXT
                30.wrap = if (document.getElementById('email4download_file_redirect') != undefined) document.getElementById('email4download_file_redirect').value = '|';
                30.field = file_redirect

                # Scroll to top and stop the html link target
                40 = TEXT
                40.value = scroll(0,0); return false;

        }


        # Redirect
          # .field enables: path, file, file_hash, form, redirect, redirect_string, redirect_string2, crdate, action
        rewrite = COA
        rewrite {
                10 = TEXT
                #10.data = getIndpEnv:TYPO3_SITE_URL # http://www.conject.com/en/ is wrong
                10.value = http://www.conject.com/
                10.wrap = /elqNow/elqRedir.htm?ref=|

                20 = TEXT
                20.field = path

                30 = TEXT
                30.field = redirect_string
                30.wrap = ?|

                40 = TEXT
                40.field = redirect_string2
                40.wrap = =|
        }


        # You can send the values via POST (CURL) to any target
                # .field enables: name, firstname, email, agb, file, file_short, elqCustomerGUID
        send2externTarget {

                # Activate sending form values to an extern target via POST (0/1)
                activate = 0

                # Target URL for POST values (like http://www.target.com/target.php)
                targetURL = http://now.eloqua.com/e/f2.aspx

                # Additional POST values (like &test=1&key=value)
                additionalData = COA
                additionalData {
                        10 = TEXT
                        10.value = &elqSiteID=1009&elqFormName=main&elqCookieWrite=0&form=download

                        # add email
                        20 = COA
                        20.wrap = &email=|
                        20 {
                                10 = TEXT
                                10.field = email
                                10.rawUrlEncode = 1
                        }

                        # add name
                        30 = COA
                        30.wrap = &name=|
                        30 {
                                10 = TEXT
                                10.field = name
                                10.rawUrlEncode = 1
                        }

                        # add firstname
                        40 = COA
                        40.wrap = &firstname=|
                        40 {
                                10 = TEXT
                                10.field = firstname
                                10.rawUrlEncode = 1
                        }

                        # add dummy company
                        50 = COA
                        50.wrap = &company=|
                        50 {
                                10 = TEXT
                                10.value = Requested download on conject.com
                                10.rawUrlEncode = 1
                        }

                        # add elqCustomerGUID
                        60 = COA
                        60.wrap = &elqCustomerGUID=|
                        60 {
                                10 = TEXT
                                10.field = elqCustomerGUID
                                10.rawUrlEncode = 1
                        }

                        # add Filename
                        70 = COA
                        70.wrap = &file=|
                        70 {
                                10 = TEXT
                                10.field = file_short
                                10.rawUrlEncode = 1
                        }

                }

        }


        # Add some dynamic Typoscript (e.g. to the admin emails)
        dynamicTyposcript {
                ai = COA
                ai.wrap = <hr />|
                ai {
                        # Current page
                        10 = TEXT
                        10.data = getIndpEnv:TYPO3_REQUEST_URL
                        10.wrap = <b>URL:</b>&nbsp;|<br />

                        # IP address
                        20 = TEXT
                        20.data = getIndpEnv:REMOTE_ADDR
                        20.wrap = <b>IP Address:</b>&nbsp;|<br />

                        # Current language
                        30 = TEXT
                        30.data = GPvar:L
                        30.wrap = <b>Frontend Language:</b>&nbsp;|<br />
                }
        }
}

# Don't forget this line in your own typoscript (if you want to use the subpart EMAIL4DOWNLOAD)
page.10.subparts.EMAIL4DOWNLOAD < plugin.tx_wtemail4download_pi1
Setup explanation
  • _enable: This is the main switch to activate/deactivate the FE plugin
  • Constants: This part is explanated in the constants (see below)
  • Form: This part defined the FE rewrite if you have checked the form checkbox in the BE module (a javascript function unhide a DIV layer – will work only if you have added the static template)
  • Rewrite: This part defined the FE rewrite if you have checked the redirect checkbox in the BE module (the a tag will be re-written)
  • Send2externTarget: This part defines the values which could be send to an extern target for db storing (e.g. in your CRM tool)
  • dynamicTyposcript: This part let you define some special marker in your HTML Templates (fill marker with Typoscript)
  • page.10.subparts.EMAIL4DOWNLOAD: Don't forget this line if you want to paste the FE plugin to a subpart
Constants
Code from ext_typoscript_constants.txt (in the extension folder)
###
# This are the default TS-constants for wt_email4download
##

plugin.wtemail4download {

        # cat=plugin.wtemail4download/file/010; type=file[html,htm,tmpl,txt]; label= Template File: HTML-template file for all views (see EXT:wt_email4download/files/templates/tmpl_email4download.html for an example)
        template = EXT:wt_email4download/files/templates/tmpl_email4download.html

        # cat=plugin.wtemail4download/file/020; type=file[html,htm,tmpl,txt]; label= Template File emails: HTML-template file for admin emails (see EXT:wt_email4download/files/templates/tmpl_email4download_email.html for an example)
        template_email = EXT:wt_email4download/files/templates/tmpl_email4download_email.html

        # cat=plugin.wtemail4download//030; type=boolean; label= Activate Plugin: (de)activate plugin complete (maybe for a special page, where you do not want the AJAX, etc...)
        enable = 1

        # cat=plugin.wtemail4download//040; type=int; label= PID where to save: Enter a PID where to save the new fe_user (0 disables function to save a new fe_user)
        pid_feuser = 0

        # cat=plugin.wtemail4download//050; type=int; label= PID Privace Statement: Enter a PID where to find your privace statement
        pid_agb = 1

        # cat=plugin.wtemail4download//060; type=boolean; label= Activate Session: If user filled out a form, the next time when he choose a file, he can download the file at once
        session = 1

        # cat=plugin.wtemail4download//070; type=text; label= Add admin E-Mail addresses: If you want to get an email if someone fills the form, add one or more email addresses (e.g. alex@test.de, alex2@test.de)
        sendEmailOnRegister =

        # cat=plugin.wtemail4download//100; type=boolean; label= Disable new fe_users: Disable all generated fe_users by default
        feuser.disable = 0

        # cat=plugin.wtemail4download//105; type=boolean; label= Login for feuser: If this is activated the currently added feuser will be logged in with his username and the password (login only available if pid_feuser and the TYPO3 feuser pid are the same)
        feuser.login = 0

        # cat=plugin.wtemail4download//110; type=text; label= Password for new fe_users: Define a default password for the new fe_users
        feuser.password = e4d

        # cat=plugin.wtemail4download//110; type=text; label= Usergroup of new fe_users: Define a one or more usergroups for the new fe_users (e.g. 1,2 for usergroup with uid 1 and uid 2)
        feuser.usergroup = 1

        # cat=plugin.wtemail4download//120; type=boolean; label= Activate for local users: The rewrite and form function is disabled for local users (with IP 192.168.) - you can activate it here
        enable4networkusers = 0

        # cat=plugin.wtemail4download//130; type=text; label= Deactivte if referer: Deactivate plugin if user comes from a special refer (like www.test.com)
        disable4referer =

        # cat=plugin.wtemail4download//140; type=text; label= Deactivte if usergroup: Deactivate plugin if there is a logged in FEUser from a usergroup (like 1,2,4)
        disable4usergroup =

        # cat=plugin.wtemail4download//150; type=text; label= Activate for IP: If you want to activate the rewrite and the form for only one ore more specified IP addresses, you can enter this IP address here (e.g. 192.168.0.100, 192.168.0.101) (Note: This function do not care about the setting _enable!)
        enable4IP =

}
Constants explanation
Name

a

Name

b

Explanation

c

Default value

d

Data type

template

a

template

b

Template File: HTML-template file for all views (see EXT:wt_email4download/files/templates/tmpl_email4download.html for an example)

c

EXT:wt_email4download/files/templates/tmpl_email4download.html

d

file[html,htm,tmpl,txt]

template_email

a

template_email

b

Template File emails: HTML-template file for admin emails (see EXT:wt_email4download/files/templates/tmpl_email4download_email.html for an example)

c

EXT:wt_email4download/files/templates/tmpl_email4download_email.htm l

d

file[html,htm,tmpl,txt]

enable

a

enable

b

Activate Plugin: (de)activate plugin complete (maybe for a special page, where you do not want the AJAX, etc...)

c

1

d

boolean

pid_feuser

a

pid_feuser

b

PID where to save: Enter a PID where to save the new fe_user (0 disables function to save a new fe_user)

c

0

d

int

pid_agb

a

pid_agb

b

PID Privace Statement: Enter a PID where to find your privace statement

c

1

d

int

session

a

session

b

Activate Session: If user filled out a form, the next time when he choose a file, he can download the file at once

c

1

d

boolean

sendEmailOnRegister

a

sendEmailOnRegister

b

Add admin E-Mail addresses: If you want to get an email if someone fills the form, add one or more email addresses (e.g. alex@test.de, alex2@test.de)

c

d

text

feuser.disable

a

feuser.disable

b

Disable new fe_users: Disable all generated fe_users by default

c

0

d

boolean

feuser.login

a

feuser.login

b

Login for feuser: If this is activated the currently added feuser will be logged in with his username and the password (login only available if pid_feuser and the TYPO3 feuser pid are the same)

c

0

d

boolean

feuser.password

a

feuser.password

b

Password for new fe_users: Define a default password for the new fe_users

c

e4d

d

text

feuser.usergroup

a

feuser.usergroup

b

Usergroup of new fe_users: Define a one or more usergroups for the new fe_users (e.g. 1,2 for usergroup with uid 1 and uid 2)

c

1

d

text

enable4networkusers

a

enable4networkusers

b

Activate for local users: The rewrite and form function is disabled for local users (with IP 192.168.) - you can activate it here

c

0

d

boolean

disable4referer

a

disable4referer

b

Deactivte if referer: Deactivate plugin if user comes from a special refer (like www.test.com)

c

d

text

disable4usergroup

a

disable4usergroup

b

Deactivte if usergroup: Deactivate plugin if there is a logged in FE User from one or some usergroup(s) (like 1,2,4)Could be used together with feuser.login (see above)

c

d

text

enable4IP

a

enable4IP

b

Activate for IP: If you want to activate the rewrite and the form for only one ore more specified IP addresses, you can enter this IP address here (e.g. 192.168.0.100, 192.168.0.101) (Note: This function do not care about the setting _enable!)

c

d

text

FAQ

How can I use my own design for the form

Have a look into the static template – there is a default CSS file – just write your own CSS file

There is an XML error if I use Internet Explorer and send some values within the form

  • If you don't use UTF-8 in your TYPO3 it could be possible that special signs (like german umlauts) in the locallang file (pi1/locallang.xml) cause an error
  • You can rewrite the locallang values in Typoscript to have a workarround (“überprüfen” => “ueberpruefen”)

How to increase the session time

  • If you want that the user should login one time and shouldn't relogin before 365 days are passed, you can use feuser.login and disable4usergroup (in constants). This settings will login the user and disable the rewriting of the links if a usergroup is logged in
  • Increase the FE_User cookie time to 365days (e.g.) - Add this to your localconf.php:$TYPO3_CONF_VARS['FE']['lifetime'] = '3600*24*365';

Todos

Encryption of the files in the source(persons with html knowledge could read the source and enter the URL to the file on there own)

Do you need a new feature? Maybe we can help you, so just write us!

Changelog

((generated))

wt_email4download version 0.1.x alpha
Update on 13.07.2009 version 0.1.10

New feature: Login fe_user after download

Update on 09.04.2009 version 0.1.9
  • Fixed problem with umlauts in FE
  • DB entries with non existing files will be deleted
  • Open files directly from backend plugin
  • Group by PID and UID in backend plugin
Update on 02.04.2009 version 0.1.8

Small change in deleting not needed db entries

Update on 30.03.2009 version 0.1.7
  • Small change in default css (for IE8)
  • email4download form could be disabled if user comes from a defined referer
Update on 12.03.2009 version 0.1.6

Switch added to disable complete plugin with constants (if you don't want to add ajax to a special page)

Update on 09.03.2009 version 0.1.5

Small change in using doorman

Update on 26.02.2009 version 0.1.4

Bugfix if session was used (Small changes in the HTML Template)

Update on 19.02.2009 version 0.1.3

Crawler function added

Update on 11.02.2009 version 0.1.2
  • Define the needed columns via Extension Manager
  • Possibility to show page ID's and tt_content uid's near every entry in the backend module
Update on 09.02.2009 version 0.1.1

Export function in backend added

Initial Release to TER on 04.02.2009 version 0.1.0

email4download available in the TER