EXT: Send-A-Card¶

Table of Contents¶

Introduction 2

What does it do? 2

What's new in version 3 2

Requirements 2

Credits 2

Sponsors 3

Users manual 4

Getting Started 4

Creating Postcards 4

Multiple series of cards 5

Multilingual sites 5

Plugin Usage Statistics 5

Administration 6

Frontend and email rendering 6

HTML Template 6

CSS Styles 6

CSS Styles for HTML Emails 6

HTML Template Markers 6

Localization 7

Adapting labels 7

Customizing the Email messages 7

Backend User Administration 7

Granting Access to Plugin Usage Statistics 7

User TSConfig 7

Database Clean Up 7

Configuration 9

Configuration steps 9

TypoScript Reference 9

Configuration FAQ 12

Simplifying the card form 12

Enabling multiple cards series in one content element 12

Using the graphical message feature 13

Branding the postcard 13

Using frames 13

To-Do List 14

Change Log 15

What does it do?¶

The Send-A-Card extension offers electronic postcard delivery:

• the card sender selects a postcard image, QuickTime video clip or Flash clip from a display of thumbnails, completes a form to specify postcard information, format and card delivery date;
• the card sender previews the card and sends it; if a future card delivery date is specified, card delivery will be delayed until the specified date (the card will be sent by a scheduler task);
• when the “card is sent”, the recipient receives an email message with a link to the card; clicking on the link, the recipient can view the card; the card may include a link to a print-friendly version;
• when the recipient views the card, the sender may be notified by email (if so requested at send time).

The Send-A-Card extension features include:

• graphical message: card text displayed with any TrueType font;
• postcard image “branding”: your logo superimposed over the image;
• handling multiple series of cards;
• multilingual site support, including Japanese;
• HTML emails;
• a back end module that displays some plugin usage statistics;
• DBAL compliance;
• TYPO3 scheduler integration;
• CSS-styled XHTML 1.0 Strict template;
• integration with the freeCap CAPTCHA (sr_freeCap) extension in order to avoid abuse;
• switching salutation mode.

You can see an example of the use of this extension on this page: http://www.lamatatena.org/en/tarjetas.html

What's new in version 3¶

• Always use utf-8 character set as default character set.
• Use TYPO3 Swift Mailer API.
• Use TYPO3 scheduler task to mail deferred cards.

Requirements¶

Version 3.2+ of the extension requires TYPO3 6.2+.

Version 3.0+ of the extension requires TYPO3 4.5+.

ImageMagick must be available in the TYPO3 configuration for the extension to operate properly.

The graphical message feature requires PHP to be compiled with ttf support.

Credits¶

The general idea of this plugin is based on sendcard 3.2.0 < http://www.sendcard.org > authored by Peter Bowyer. The plugin is a complete remake within the Typo3 framework, leaving little resemblance with the code of the original script that inspired it. Yet, this plugin is made available in the Typo3 public online extension repository with the permission and agreement of Peter Bowyer.

Thanks to Martin Kutschker for his numerous helpful corrections, suggestions and improvements.

Thanks to Jörg Schaller http://www.jorgo.org and again to Martin for helping me understand the charsets and translations issues.

Many thanks to Chie Hiraki for the Japanese translation!

This extension incorporates a script borrowed from extension Salutation Switcher (salutationswitcher) authored by Oliver Klee to allow to set formal or informal salutation mode.

Sponsors¶

You may sponsor further development of this extension by sending your contribution to stanislas.rolland@sjbr.ca through moneybookers.com or PayPal , or by contacting the author .

Getting Started¶

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.

After these two steps, a card selection page will have been defined and the Send-A-Card plugin will have been inserted in an element of this page. This is the page that the card sender will use, in the front end, to select a postcard.

Creating Postcards¶

Now, you need to provide cards that can be sent.

In order to do this, you could position yourself on the card selection page in the page tree of your site, and insert on it a new record of type “Postcard”. However, we suggest instead that you first create a Sysfolder, give a meaningful name to this Sysfolder corresponding to your set of cards, and insert your cards in that Sysfolder.

In any case, on selecting record type “Postcard”, you should get a window like the following:

• Give a title to your card. It will serve as a caption displayed under the image of the card.
• Select or upload an image, a QuickTime clip or a Flash animation for inclusion on the postcard.
• You may specify the dimensions of the image as you want it displayed on the postcard. If you selected a QuickTime movie clip or a Flash animation, then this is required .
• If you selected a QuickTime movie clip or a Flash animation, select or upload an alternative image that will be used on the card image selection page (you do not want to start all the clips and animations on this same page!). It will also be used on the printer-friendly page in place of the movie clip or animation.
• You may specify the dimensions of the alternative image as you want it displayed on the printer-friendly version of the postcard.
• Finally, you may include a link to a page of your site. If you do, then the title or caption of the image will include a link to that page.

On the card selection page, edit the Postcards Insert plugin element and add your Sysfolder in the Startingpoint field.

Cards may now be selected and sent from the front end.

You can add further images and clips for the visitors to choose from.

Multiple series of cards¶

You may want to offer a selection among multiple series or bundles of cards. There are two ways of doing this.

One way to present multiple series of cards on the card selection page is to present them in as many content elements. This is done as follows:

• create a Sysfolder for each cards series, and insert the cards in each Sysfolder;
• on the card selection page, insert the Postcards plugin in as many content elements as you have cards series to present;
• on each plugin insert, add one of your card series Sysfolders in the field Startingpoint;
• create another page (if not done at configuration time) on which the card form will be presented; this page must be identified in the TS template with the setting: formPID = your_page_id ; note that if the property formPID is not set, the form will be displayed on the card selection page and it will be displayed as many times as the plugin is inserted on that page!

Another way to present multiple series of cards is to present them is a single content element. This is done as follows:

• you must first ensure that this feature is enabled through the TS template setting enableAlternateSelectionTemplate = 1 (see Configuration section);
• create a Sysfolder for each cards series, and insert the cards in each Sysfolder; the title of the Sysfolder will be the title of the series;
• on a single “Insert plugin” element of the card selection page, add each of the Sysfolders in the field Startingpoint (the field may contain many);
• the cards series will be presented, preceded by their titles, as a single content element.

When the second way is enabled (enableAlternateSelectionTemplate = 1), you can combine both methods on the selection page!

Multilingual sites¶

The Send-A-Card extension should behave correctly in a one-tree multilingual site. In particular, the link to the postcard included in the the email should link back to the site in the language of the sender.

The title of a card series contained in a Sysfolder may be translated by creating a record of type Alternative Page Language in the Sysfolder.

Once an alternative page language record has been created in the Sysfolder, you can translate each card of the series. This is done the same way you translate content elements.

Plugin Usage Statistics¶

The Send-A-Card extension includes a back end module that displays statistics about the most frequently and most recently sent cards. The module is accessible in the Web section of the back end menu to back end users and groups that have been granted access to it.

Frontend and email rendering¶

Localization¶

Backend User Administration¶

Database Clean Up¶

The plugin configuration setup defines a date: oldDay/oldMonth/oldYear. All postcards sent before that date will be marked as 'deleted'. You may wish to change this date from time to time.

Configuration steps¶

These are the steps to configuring the Send-A-Card plugin:

Install the extension using the Extension Manager.

Add the following static template to your TypoScript template: 'Send-A-Card CSS-styled'

Create a page on which the plugin will be inserted and where the card sender will select, create and send its card; do the same for the page where the recipient will view her card (you could use the same page), and optionally, add a page on which the plugin will be inserted and from which the card recipient will be able to print the card; on each of these 3 pages, create a content element of type “Plugin insert”, and insert the plugin 'Postcards'; set the TS template properties createPID, viewPID and printPID to the page id's of the pages you created.

If you wish to be able to include multiple cards series in different content elements on the selection page, then create a form filling page, create a content element of type “Plugin insert“ on it, and insert the plugin 'Postcards'; set the TS template property formPID = your_page_id .

You may also create a preview page; if you do, create a content element of type “Plugin insert“ on it, and insert the plugin 'Postcards'; set the TS template property previewPID = your_page_id .

Create a directory where you will store your music files. You may want to copy in this directory the example files included in the extension directory.

Use the TYPO3 Scheduler extension to schedule the task “Send-A-Card: Send deferred cards “. The task may be set to be executed every hour or every day. If you disable the date selection option (disableSendDate = 1) of the plugin TS configuration, then you do not need to schedule this task. The task configuration requires to specify the page id on which the card will be presented to the recipient.

Review the plugin properties described below. All these properties may be conveniently edited using the Constant Editor TS template tool. Make sure you set correctly:

• file.templateFile: the location of your HTML template;
• dir: the directory where postcard images will be stored by the plugin; by default: uploads/tx_srsendcard, created during installation of the extension;
• musicDir: directory where you will store music files;
• cardMusicFiles: list of music file names; must be the same length (and same order!) as the length of the list card_music_labels in pi1/locallang.xml (maybe overridden in TS setup, see Localization);
• createPID, formPID, previewPID, viewPID and printPID: the page id's where the plugin will be inserted, and corresponding createType, formType, previewType, viewType and printType;
• cardFontfaces: if you override the default list, make sure to modify correspondingly the property fontface_labels in pi1/locallang.xml by overriding it in your TS setup (see Localization);
• enableAlternateSelectionTemplate: set to 1, if you want to enable the possibility of displaying multiple cards series within the same content element (same plugin insert).

TypoScript Reference¶

Configuration FAQ¶