.. include:: /Includes.rst.txt

.. highlight:: typoscript

.. _content-objects:

===============
Content objects
===============

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

..  contents::
    :local:
    :depth: 2

.. _content-objects-usage:

How the mail page uses them
===========================

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

..  code-block:: typoscript
    :caption: 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 :file:`EXT:mail/Configuration/TypoScript/Styles/setup.typoscript` adds a second
:typoscript:`SCSS` object, which compiles the file configured in
:typoscript:`plugin.mail.settings.scss.modifications` (see :ref:`SCSS settings
<ts-content-scss-settings>`):

..  code-block:: typoscript
    :caption: EXT:mail/Configuration/TypoScript/Styles/setup.typoscript

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

.. warning::

   The :typoscript:`css` property of :typoscript:`EMOGRIFIER` is a :typoscript:`COA`.
   The indexes :typoscript:`10` (Foundation for Emails) and :typoscript:`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 :typoscript:`30`:

   ..  code-block:: typoscript
       :caption: Add your own CSS to the mail

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

.. _content-object-emogrifier:

EMOGRIFIER
==========

:typoscript:`EMOGRIFIER` renders the HTML given in :typoscript:`html`, writes the rules
of the given :typoscript:`css` as inline :html:`style` attributes into it and optionally
removes the class attributes afterwards. It uses the
`CssInliner <https://github.com/MyIntervals/emogrifier>`__ of the package
:php:`pelago/emogrifier`.

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

Properties
----------

.. _ts-emogrifier-html:

.. confval:: html

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

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

.. _ts-emogrifier-css:

.. confval:: css

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

   The CSS which is inlined, usually a :typoscript:`COA` of several :typoscript:`SCSS`
   objects. Style blocks which are already part of the HTML are inlined as well. See the
   :ref:`warning above <content-objects-usage>` before you add your own CSS.

.. _ts-emogrifier-extract-content:

.. confval:: extractContent

   :type: boolean
   :Default: 0
   :Path: mail.10.extractContent

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

.. _ts-emogrifier-options:

.. confval:: options

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

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

   ..  code-block:: typoscript
       :caption: Example

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

   disableStyleBlocksParsing
      Do not read the :html:`<style>` blocks of the HTML.

   disableInlineStyleAttributesParsing
      Do not merge already existing :html:`style` attributes.

   addAllowedMediaType / removeAllowedMediaType
      Add or remove a media type (e.g. :typoscript:`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 :php:`pelago/emogrifier` 7.3 or higher.

.. _ts-emogrifier-remove-class-attributes:

.. confval:: removeClassAttributes

   :type: boolean
   :Default: 0 (1 in the site set :typoscript:`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 :ref:`Removing class attributes
   <content-object-emogrifier-classes>` for the sub properties.

   .. versionchanged:: 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.

.. _ts-emogrifier-keep-on-tags:

.. confval:: 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. :typoscript:`table, td`.

   .. versionadded:: 4.3.0

.. _ts-emogrifier-keep-classes:

.. confval:: 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. :typoscript:`body, btn`. All other
   classes are removed. The comparison is case sensitive.

   .. versionadded:: 4.3.0

.. _ts-emogrifier-smart:

.. confval:: removeClassAttributes.smart

   :type: boolean
   :Default: 0
   :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 :php:`HtmlPruner::removeRedundantClassesAfterCssInlined()`
   of :php:`pelago/emogrifier` does it. They are added to :ref:`keepClasses
   <ts-emogrifier-keep-classes>`.

   .. versionadded:: 4.3.0

.. _content-object-emogrifier-classes:

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:

..  code-block:: typoscript
    :caption: 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 :typoscript:`smart = 1` the class `body` stays on its element, all other
classes are removed. Alternatively you can list the classes yourself with
:ref:`keepClasses <ts-emogrifier-keep-classes>` and
:ref:`keepOnTags <ts-emogrifier-keep-on-tags>`. 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 :html:`emogrify` ViewHelper:
:html:`removeClassAttributes`, :html:`keepOnTags`, :html:`keepClasses` and
:html:`smartClassRemoval`.

.. _content-object-scss:

SCSS
====

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

Properties
----------

.. _ts-scss-file:

.. confval:: file

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

   Path to the SCSS file, e.g. :typoscript:`EXT:mail/Resources/Public/Scss/mail.scss`.
   Only files with the extension :file:`.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 :file:`EXT:` path.

.. _ts-scss-cache-tags:

.. confval:: 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 :typoscript:`mail` for the modifications.

.. _content-object-scss-variables:

SCSS variables
--------------

All TypoScript constants (site settings) below :typoscript:`plugin.mail.settings.scss.`
are passed to the compiler as SCSS variables, named like the constant without this prefix.
The constant :typoscript:`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 :ref:`SCSS settings
<ts-content-scss-settings>` of the TypoScript reference.

..  code-block:: typoscript
    :caption: 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 :file:`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.

.. seealso::

   *  :ref:`TypoScript settings <typoscript-settings>` of the mail page and the SCSS variables
   *  :ref:`Site sets and settings <site-settings>`