blueways/bw-email

TYPO3 extension for creating responsive email templates

v2.1.7 2021-07-29 07:53 UTC

Requires

• ext-json: *
• maikschneider/inky: 1.3.6.*
• tijsverkoyen/css-to-inline-styles: ^2.2

Requires (Dev)

• bk2k/bootstrap-package: 9.1.*
• typo3/cms-base-distribution: 9.5.*

MIT

• Maik Schneider

• zurb foundation
• typo3
• Responsive Email

README

This is the offical documentation of the bw_email extension.

About

You can use this extension to send whole pages or any other element that has a TCA definition.

The templates are parsed with Zurb Foundation Inky. You can use the Inky markup in your fluid templates to generate the table markup needed for most mail clients.

Installation

• Require via composer `composer require blueways/bw-email`
• Activate in Extension Manager
• Include static TypoScript template

Templates

The extensions offers some default templates located in `ÈXT:bw_email/Resources/Private/Templates`. You can override the templates by setting the paths via constants:

plugin.tx_bwemail {
	view {
		templateRootPath =
		partialRootPath =
		layoutRootPath =
    }
}		

To register new templates, use PageTS:

mod.web_layout.EmailLayouts {
    new_template {
        title = NewTemplate
        config {
            icon = EXT:my_ext/Resources/Public/Icons/MyIcon.svg
            backend_layout {
                colCount = 1
                rowCount = 1
                rows {
                    1 {
                        columns {
                            1 {
                                name = LLL:EXT:bw_email/Resources/Private/Language/locallang.xlf:backend_layout.column.normal
                                colPos = 0
                            }
                        }
                    }
                }
            }
        }
    }
}

Default mail settings

plugin.tx_bwemail {
    settings {
            css = EXT:bw_email/Resources/Public/Css/app.css
            senderAddress = [e-mail]
            senderName = Example sender name
            replytoAddress =
            subject = Example subject
            template = Default
            showUid = 1
            recipientAddress =
    }
}

Data sources

Right from the start you can send single Emails to an email address from inside the email wizard. If you like to send emails to multiple people, you can create a Email data source entry and select one of the following build-in connectors:

• fe_users
• CSV file (upcoming)

Usage in other extensions

You can use the `Blueways\View\EmailView in your own extension to render responsive email HTML with Inky syntax. It works just like the `StandaloneView``.

Extend

You can use the DataSource-Provider or create your own ContactProvider.

DataSource model

If you like to configure your source via Backend, you can use the existing DataSource model. Create your own Model by extending the `ContactSourceModel and implement thegetContacts()` method.

Don't forget to register the inheritance via typoscript:

config.tx_extbase.persistence.classes {
    Blueways\BwEmail\Domain\Model\ContactSource {
        subclasses {
            Vendor\Extension\YourModel = Vendor\Extension\YourModel
        }
    }
    Vendor\Extension\YourModel.mapping {
        recordType = Vendor\Extension\YourModel
        tableName = tx_bwemail_domain_model_contactsource
    }
}

ContactProvider service

If you like to use external data, you can write your own ContactProvider. Just extend from `Blueways\BwEmail\Service\ContactProvider` and register the class via Hook:

Known issues

• CSS files need to be hard coded in email template (see Default.html)
• Inline RTE links are wrapped with an additional `<p></p>` that causes line breaks
• Internal links may be broken

Usage in other content elements

It is possible to use the email wizard in other content elements like Textmedia or News: Just add an element with the TCA-RenderType "sendMailButton". Here is an example of how to add a Send Mail button to tt_content elements:

// TCA/Overrides/tt_content.php
<?php

$tempColumns = [
    'mail_button' => [
        'label' => 'Send this tt_content',
        'config' => [
            'type' => 'passthrough',
            'renderType' => 'sendMailButton',
        ],
    ]
];

ExtensionManagementUtility::addTCAcolumns('tt_content', $tempColumns);
ExtensionManagementUtility::addToAllTCAtypes(
    'tt_content',
    'mail_button',
    '',
    'before:CType'
);

The current record will be available in the Fluid Template as `{record}`.

To inject additional elements or override default settings you can use the `tableOverrides` TypoScript setting.

plugin.tx_bwemail {
    settings {
        subject = Default subject in all places
        tableOverrides {
            tt_content {
                subject = New subject
                recipientName = FIELD:header
                typoscriptSelects {
                    latestNews {
                        table = tx_news
                        select {
                            pidInList = 3
                            orderBy = sorting
                            max = 3
                        }
                    }
                }
            }
        }
    }
}

With the `typoscriptSelectssetting you can insert records to the email template. In the example above, you can display the latest news records with<f:for each="{latestNews}" as="news">{news.title}</f:for>`.

Todo

• Better translations
• Better default template organisation
• Absolute URL handling for new v9
• Move provider settings to TypoScript

Improvement ideas

• embed images in message
• separate backend module
• send mail log
• sass compiler for Foundation for Email