Skip to content

Latest commit

 

History

History
134 lines (110 loc) · 5.19 KB

02_Templating.md

File metadata and controls

134 lines (110 loc) · 5.19 KB

Silverstripe Sendy - Templating

Templating for this module is the same as if you were creating templates for the silverstripe-elemental module.

We do not provide default blocks, but it should be sufficiently easy to create new Blocks following the elemental documentation.

Layout Template

Update the Layout template by adding the following file:

<!-- mysite/templates/Syntro/SilverStripeSendy/Model/SendyCampaign.ss -->
<!DOCTYPE html>
<html>
    <head>
        <!-- ... -->
    </head>
    <body>
        <!-- ... -->
        $ElementalArea
        <!-- ... -->
    </body>
</html>

This builds the encapsulating Layout for every Newsletter.

Note: Use the $Subject in the title tag

Using multiple styles

Silverstripe Sendy supports multiple styles using the configuration API. The approriate style for a given newsletter can be set in its CMS interface. To configure styles, proceed as follows.

  1. Define your templates as key-value pairs in your app.yml. The value represents the front-facing name:
# /app/_config/app.yml
Syntro\SilverStripeSendy\Model\SendyCampaign:
  styles:
    red: Red Style
    blue: Blue Style
  1. Place the templates in the destination given in the previous section with the naming SendyCampaign_$key, e.g.: mysite/templates/Syntro/SilverStripeSendy/Model/SendyCampaign_red.ss

Note: Silverstripe Sendy will fall back to SendyCampaign.ss if the configuration is faulty, a template file is missing, or a template is not set in the CMS. It is thus strongly recommended to provide a SendyCampaign.ss.

Styling Elemental blocks

This module also supports styles for Elemental blocks. Since we have to rely on pure HTML for styling e-mails, you will have to provide a template for every desired combination of SendyCampaign style and block style.

  1. Define your Elemental styles like so:
# /app/_config/app.yml
Model\Elements\SendyContent:
    styles:
        1col: Single column
        2col: Double column
  1. Place the templates in the appropriate SendyContent_$blockstyle_$campaigntheme, e.g.: mysite/templates/Syntro/SilverStripeSendy/SendyContent_1col_red

Class names differ from the example above, as you will generally write your own Elemental blocks and include them in your page, and not in the module.

Creating Blocks

Creating blocks is done the same way as regular blocks used by the silverstripe-elemental module, with some gotchas explained here.

Using a Custom Holder Template

Your Newsletter blocks should use a custom holder template which is different from the one used by your page ones. To do this, add this to your newsletter blocks:

/**
 * @var string
 */
private static $controller_template = 'NewsletterElementHolder';

Then, create a file templates/DNADesign/Elemental/Layout/NewsletterElementHolder.ss which uses the correct holder markup.

Using the stylability extension

Silverstripe-Sendy includes an extension to provide stylability for your blocks despite the limiations of mails. When writing your own blocks, be sure to include the extension in the code:

// /app/src/Model/Elements/SendyContent.php
class SendyContent extends BaseElement
{
    private static $extensions = [
        SendyContentExtension::class,
    ];

    private static $controller_template = 'NewsletterElementHolder';
}

Similarly to newsletter styles, you can then proceed to define the styles in your config:

# /app/_config/app.yml
Model\Elements\SendyContent:
    styles:
        1col: Single column
        2col: Double column

Silverstripe Sendy will accordingly check for a template named SendyContent_ElementalArea_$blockstyle_$campaignstyle, e.g. as templates/Syntro/SilverStripeSendy/Model/SendyContent_ElementalArea_1col_red.ss.

Note: Due to the limiations of mails, you will have to provide a file for every desired permutation of newsletter and block style. If the file cannot be found, Silverstripe Sendy will fall back on less specific files, which might yield unexpected visual results.

Limit Blocks to Newsletter Use

It is important to understand the difference between a block in your newsletter compared to a block in your regular page layout. A block utilized in a newsletter campaign must not use external css, unlike a regular block. It is therefore necessary to limit the elements used for newsletter to only appear on the campaign. For this, follow the docs of the elemental module: https://github.com/silverstripe/silverstripe-elemental#limit-allowed-elements

You should always disable the blocks you create for newsletters in regular pages and only enable newsletter blocks for sendy campaigns.

Syntro\SilverStripeSendy\Model\SendyCampaign:
  allowed_elements:
    - Model\Elements\Newsletter\Content
# Use your actual class here
ElementalPage:
  disallowed_elements:
    - Model\Elements\Newsletter\Content

HTMLEditorConfig

As Newsletters do not have the same capabilities as pages in the CMS do, we have to apply a custom config to all HTMLEditor fields. Do this by adding:

$contentField = $fields->fieldByName('Root.Main.HTML');
$contentField->setEditorConfig('newsletter');