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.

You can find a full working plugin that adds a block to the Composer on GitHub.

Please do not add your block inside the Newsletter plugin folders and do not modify the provided blocks: everything will be restored on plugin update (by WordPress).

Registration of custom blocks

The correct way to add your custom blocks is to call our registration method by listening to the newsletter_register_blocks 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 that wants to register a custom block you can create a sub-folder named my-block where to put your block files and reference them 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');
});

The folder must contain at least three files: block.php, options.php, and icon.png.

See the instructions below on file naming and organization.

Old and deprecated method

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

How to code a custom block

A block is finally a piece of HTML written in a way to render correctly on email clients. To make that easier, Newsletter wraps your generated HTML with a 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 a few other standard layout attributes (see later on this page).

The wrapper creates a free area (usually with no padding) where the block content is rendered. The area is centered but you can create HTML with different alignments. Below is 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 as 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 blocks)
Description: 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, the Newsletter plugin has an inliner so if your block code is:

<style>
.link {
border: 1px solid #000;
color: #333;
}
</style>
<a href="#" inline-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 CSS works only with simple CSS definitions (the class .link) and only on elements with that specific single class. An element with an attribute inline-class="link footer" won’t be processed.

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.

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 copying one of our block options file and using the $fields object which is a 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 creates the fields with the correct name and HTML structure. You can find many examples in the Newsletter plugin 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.