Composer Blocks

Blocks can be dynamically and easily added to the composer with a little effort. A block is a small set of files: an icon, a block renderer and block options.

The composer looks for registered blocks (see later) after loading the core ones and add them to the tool set.

Since Newsletter 6.1.1.

Registration of custom blocks

Add your block to custom blocks folder

The easy way is to create a new folder with the name of your block in the wp-content/extensions/newsletter/blocks, e.g. wp-content/extensions/newsletter/blocks/my-block.

This name has to be unique and different from all others blocks, without spaces. You can use a prefix like xyz-myblockand please note that the folder name will be “normalized” to lowercase, all not a-z, 0-9, dash, and underscore characters will be removed.

Then copy the files from one of the provided core blocks (for example wp-content/plugins/newsletter/emails/blocks/cta) in the newly created folder, so the structure has to be:

  • wp-content/extensions/newsletter/blocks/my-block
    • block.php
    • icon.png
    • options.php

and simply edit them according to the How to code a custom block.

Registering your custom blocks

Another way to add your custom blocks is to call our registration method listening to the newsletter_blocks_dir filter in this way:

add_action('newsletter_register_blocks', 'my_newsletter_register_blocks');
function my_newsletter_register_blocks() {
  $dir = ...; // Full path to your block folder
  TNP_Composer::register_block($dir);
}

Where $dir is the path to your custom block folder. For example, if you have a plugin which want to register a custom block you can create a sub-folder named my-block where to put your block files and reference it as __DIR__ . '/my-block':

add_action('newsletter_register_blocks', 'my_newsletter_register_blocks');
function my_newsletter_register_blocks() {
  $dir = __DIR__ . '/my-block';
  TNP_Composer::register_block($dir); 
}

or more compactly with an anonymous function:

add_action('newsletter_register_blocks', function () {
  TNP_Composer::register_block(__DIR__ . '/my-block');
});

How to code a custom block

A block is finally a piece of HTML coded in a way to render correctly on email clients. To make that more easy, Newsletter wraps your generated HTML with few tags needed for compatibility with old clients (Outlook), but you don’t need to care about them even if you see them in the generated HTML source.

The wrapper manages automatically the block background and few other standard layout attributes (see later in this page).

The wrapper creates a free area (usually with no padding) where the block content is rendered. The area is centered but of course you can create HTML with different alignments. Below an example of what could be a simple call to action block content:

<a href="#" stye="display: inline-block; padding: 10px; background-color: #000; color: #fff">Buy now!</a>

Of course the link colors (background and foreground) will come from your block options, as well other parameters you want to add, like a font size or font family, rounded corner and so on.

The block header

A block (to be a block) must declare its nature. So the block.php file must start with:

<?php
/*
 * Name: Call To Action
 * Section: content
 * Description: Call to action button
 */

That is what Newsletter looks at to identify a block and add it to the tool set. Please see the standard packaged blocks in emails/blocks folder for examples and starting code.

  • Name: is your block name
  • Section: is where your block should be listed (header for header blocks, content for content blocks and footer for footer related blocks)
  • Description: is a short description

CSS inliner

Email clients want CSS styles inline on elements since they can strip away the <style></style> block (actually many email clients are now fully supporting them). To make the block coding easier, Newsletter has an inliner so if your block code is:

<style>
.link {
border: 1px solid #000;
color: #333;
}
</style>
<a href="#" class="link">Buy now!</a>

the resulting code will be:

<a href="#" class="link" style="border: 1px solid #000; color: #333;">Buy now!</a>

Inlining of CSS works only with simple CSS definition (the class .link) and only on elements with that specific single class. An element with attribute class="link footer" won’t be processed. The class attribute is anyway left intact on the elements. This inliner, even if rudimentary, is extremely useful to code blocks with enough readability. The style attribute on elements must be removed if you use the inliner.

When you cannot use simple class attributes, you can use a special attribute inline-class. It is not standard, it’s only detected by Newsletter and replaced with a style. An example:

<style>
.link {
border: 1px solid #000;
color: #333;
}
</style>
<a href="#" class="some-class" inline-class="link" >Buy now!</a>

the resulting code will be:

<a href="#" class="some-class" stye="border: 1px solid #000; color: #333;">Buy now!</a>

Standard options

The block renderer wraps each block in a table, hence it can add some attributes to that table, like padding and background. The generator looks at the options array and search options named as:

  • block_background (eg. #FFFFFF)
  • block_padding_top (eg. 20 – they are pixels)
  • block_padding_bottom
  • block_padding_ right
  • block_padding_left

and applies them to the wrapping table.

Note that options starting with block_ are generally reserved and can be used only if documented.

It is not required to make those standard options available to the user, it’s possible to just set them inside the block.php file so they can be found by the rendered.

For example if your block needs always 20 pixels of padding and a grey background, you can add the code below in your block:

...
$options['block_padding_top'] = 20;
$options['block_padding_bottom'] = 20;
$options['block_padding_left'] = 20;
$options['block_padding_right'] = 20;
$options['block_background'] = '#e0e0e0;

The icon

The icon must be a PNG and named icon.png. You can find an “empty” icon inside the plugin images folder named block-icon.png.

Custom options

A block without options is probably useless. If the block folder contains a file named options.php, this file is used to render a form where the user can configure the block. All the collected options are stored inside the $options variable (it is an array) and available inside the block.php.

While the custom options form has a free layout, we suggest to start copying one of our block options file and using the $fields object which is an helper to generate correctly different kinds of fields (text, select, checkbox, media selector).

Default options

To be sure the first rendering of the block has some defaults set, you can start your block with:

$default_options = array(
    'text' => 'Example of default option value',
    'url' => 'Another option value,
    'block_background' => '#ffffff',
    'block_padding_top' => 20,
    'block_padding_bottom' => 20,
    'block_padding_left' => 20,
    'block_padding_right' => 20
);

$options = array_merge($default_options, $options);

The $fields object

Configuration form fields can be generated using the $fields helper which automatically create the fields with the correct name and HTML structure. You can find many examples in Newsletter core block (see the emails/blocks folder).

Note the special method $fields->block_commons() which generated the common block field (padding, background and so on) which should always be present. This special set of fields will be improved over time with other common block attributes.