.. You may want to use the usual include line. Uncomment and adjust the path. .. include:: ../Includes.txt ================ EXT: Send-A-Card ================ :Author: Stanislas Rolland :Created: 2009-02-17T10:51:40 :Changed by: Stanislas Rolland :Changed: 2014-10-20T13:16:40.800000000 :Email: typo3(arobas)sjbr.ca :Info 2: Stanislas Rolland :Info 3: :Info 4: EXT: Send-A-Card Extension Key: **sr\_sendcard** Copyright 2005-2014, Stanislas Rolland, 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 .. _generated: ((generated)) ============= .. _Table-of-Contents: 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** .. _Introduction: Introduction ============ .. _What-does-it-do: 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: 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: 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: 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: 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 `_ . .. _Users-manual: Users manual ============ .. _Getting-Started: 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: 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: |img-1| - - 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: 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: 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: 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. .. _Administration: Administration ============== .. _Frontend-and-email-rendering: Frontend and email rendering ---------------------------- .. _HTML-Template: HTML Template ^^^^^^^^^^^^^ The Send-A-Card plugin uses up to 5 pages that are created at configuration time: - one page on which the card sender will select the image of the card; - one page on which the card sender will specify the look and contents of the card; - one page on which the card sender will preview and send the card; - one page on which the recipient will view her card; - one print-friendly page from which the recipient can print her card. The look and feel of these pages is determined by the HTML template associated with the plugin. Each page has its own subpart. There are also subparts for the email messages to the recipient and to the sender. The default template is specified in the static template **Send-A-Card CSS-styled** . Do not delete any HTML tag containing hidden or submit tags. .. _CSS-Styles: CSS Styles ^^^^^^^^^^ Default CSS styles are defined in the default TS template setup. 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\_srsendcard\_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\_srsendcard\_pi1.\_CSS\_DEFAULT\_STYLE > Some elements of the card itself are styled by the selector **.tx- srsendcard-pi1-card** . Some styles associated with this selector are defined within in-line