Content objects

This extension brings two TypoScript content objects, which are used to build the mail page: SCSS compiles SCSS files to CSS and EMOGRIFIER writes this CSS as inline styles into the HTML of the mail. Many mail clients ignore or strip the <style> block, inline styles are the only reliable way to style a mail.

How the mail page uses them

The mail page object of the site set mediaessenz/mail (see EXT:mail/Configuration/TypoScript/Mail/setup.typoscript) is built like this:

EXT:mail/Configuration/TypoScript/Mail/setup.typoscript (shortened)

mail = PAGE
mail {
    10 = EMOGRIFIER
    10 {
        extractContent = 0
        removeClassAttributes = 1

        css = COA
        css {
            10 = SCSS
            10.file = EXT:mail/Resources/Public/Contrib/foundation-mail/foundation-emails.scss
        }

        html = FLUIDTEMPLATE
        html {
            templateName = Html
        }
    }
}

The file EXT:mail/Configuration/TypoScript/Styles/setup.typoscript adds a second SCSS object, which compiles the file configured in plugin.mail.settings.scss.modifications (see SCSS settings):

EXT:mail/Configuration/TypoScript/Styles/setup.typoscript

mail.10.css {
    20 = SCSS
    20.file = {$plugin.mail.settings.scss.modifications}
    20.cacheTags = mail
}

Warning

The css property of EMOGRIFIER is a COA. The indexes 10 (Foundation for Emails) and 20 (modifications) are already used by the extension. Assigning your own CSS to one of these indexes replaces the extension's styles, the mail loses e.g. its container width, padding and background colors. Use a free index like 30:

Add your own CSS to the mail

mail.10.css.30 = TEXT
mail.10.css.30.value = a:hover { color: #ff0000 !important; }

EMOGRIFIER

EMOGRIFIER renders the HTML given in html, writes the rules of the given css as inline style attributes into it and optionally removes the class attributes afterwards. It uses the CssInliner of the package pelago/emogrifier.

CSS rules which cannot be inlined, e.g. rules with pseudo classes like a:hover or media queries, stay in a <style> block in the <head> of the mail.

Properties

html

type: cObject
Default: (empty)
Path: mail.10.html

The HTML to which the styles are applied, usually a FLUIDTEMPLATE.

css

type: cObject
Default: (empty)
Path: mail.10.css

The CSS which is inlined, usually a COA of several SCSS objects. Style blocks which are already part of the HTML are inlined as well. See the warning above before you add your own CSS.

extractContent

type: boolean
Default
Path: mail.10.extractContent

Returns only the content between the <body> tags. The <head> and with it the <style> block with the rules which could not be inlined are dropped then. Do not enable it if you use pseudo classes like :hover.

options

type: array
Default: (empty)
Path: mail.10.options

Options of the CSS inliner. Every option is only applied if it is set.

Example

mail.10.options {
    addExcludedCssSelector = .no-inline
}

disableStyleBlocksParsing: Do not read the <style> blocks of the HTML.
disableInlineStyleAttributesParsing: Do not merge already existing style attributes.
addAllowedMediaType / removeAllowedMediaType: Add or remove a media type (e.g. print), whose rules are inlined.
addExcludedSelector: Do not inline rules for elements matching this selector (.a).
addExcludedCssSelector / removeExcludedCssSelector: Do not inline rules with this selector. Requires pelago/emogrifier 7.3 or higher.

removeClassAttributes

type: boolean
Default: 0 (1 in the site set mediaessenz/mail)
Path: mail.10.removeClassAttributes

Removes the class attributes from the mail after the CSS has been inlined. This reduces the size of the mail. See Removing class attributes for the sub properties.

Changed in version 4.3.0

Class attributes are now removed from every element. Before, the class of an element was kept if it had no other attribute.

removeClassAttributes.keepOnTags

type: string (comma separated list of tag names)
Default: (empty)
Path: mail.10.removeClassAttributes.keepOnTags

The class attributes of these tags are kept completely, e.g. table, td.

New in version 4.3.0

removeClassAttributes.keepClasses

type: string (comma separated list of class names)
Default: (empty)
Path: mail.10.removeClassAttributes.keepClasses

These classes are kept on all other elements, e.g. body, btn. All other classes are removed. The comparison is case sensitive.

New in version 4.3.0

removeClassAttributes.smart

type: boolean
Default
Path: mail.10.removeClassAttributes.smart

Keeps the classes which are still needed by CSS rules that could not be inlined, for example the class body for the rule .body a:hover. The classes are detected automatically, the same way as HtmlPruner::removeRedundantClassesAfterCssInlined() of pelago/emogrifier does it. They are added to keepClasses.

New in version 4.3.0

Removing class attributes

The class attributes are removed after the CSS has been inlined, because the rules are matched with the classes. Without further settings all classes are removed. That breaks rules which could not be inlined, like a hover color of links:

Hover color of links, kept by the "smart" removal

mail.10.css.30 = TEXT
mail.10.css.30.value = .body a:hover { color: #ff0000 !important; }

mail.10.removeClassAttributes = 1
mail.10.removeClassAttributes.smart = 1

With smart = 1 the class body stays on its element, all other classes are removed. Alternatively you can list the classes yourself with keepClasses and keepOnTags. All three settings can be combined.

Note

Pseudo classes like :hover are not supported by every mail client. Classic Outlook for Windows ignores them. Define the normal color with a normal rule, so the mail looks fine without the hover effect.

The same options exist as arguments of the emogrify ViewHelper: removeClassAttributes, keepOnTags, keepClasses and smartClassRemoval.

SCSS

SCSS compiles a SCSS file to compressed CSS and returns it as string, so it can be used directly as css of EMOGRIFIER. The compiler is scssphp/scssphp.

Properties

file

type: string
Default: (empty)
Path: mail.10.css.10.file

Path to the SCSS file, e.g. EXT:mail/Resources/Public/Scss/mail.scss. Only files with the extension .scss are compiled. If the property is empty or the file has another extension, an empty string is returned. Other SCSS files can be imported with @import, relative to the file or with an EXT: path.

cacheTags

type: string
Default: (empty)
Path: mail.10.css.10.cacheTags

Cache tags of the page caches, which are cleared if the SCSS file has been compiled again. The extension uses mail for the modifications.

SCSS variables

All TypoScript constants (site settings) below plugin.mail.settings.scss. are passed to the compiler as SCSS variables, named like the constant without this prefix. The constant plugin.mail.settings.scss.primary-color is available as $primary-color in the SCSS files.

The available variables and their defaults are listed in the SCSS settings of the TypoScript reference.

Change the primary color in the TypoScript constants of your site package

plugin.mail.settings.scss.primary-color = #c0392b

Compiled files and errors

The compiled CSS is cached in typo3temp/assets/mail/css/ and compiled again if the SCSS file or one of the variables changes.
If a SCSS file uses a variable which is not defined, the error is shown as red text at the top of the mail. This makes the mistake visible in the preview of the mail wizard.
Any other error produces no CSS (empty string), the mail is then rendered without these styles.