Newsletter Themes

Use the forum to discuss or ask for help. Thank you!

Newsletter 3.0 has a new theme structure that is not completely compatible with previous plugin versions. It’s important to read this page to understand the theme system and how to eventually migrate old custom themes to the new format.

Where are themes located?

As with Newsletter 2.5, there are different themes for different modules: the ‘Newsletters’ Module has its own themes, while the ‘Feed by Mail’ and ‘Follow Up’ Module have their own themes.

Why? Because each module needs themes that work in a slightly different mode. For example, ‘Feed by Mail’ Module requires themes to compose automatically an email with posts that have not already been sent to subscribers, while ‘Follow Up’ needs only a “frame” where to insert the messages you configure.

Each module, now confined in its own specific folder, must have a themes sub-folder in which Newsletter can look for its themes. Of course if a module does not require themes, then there will be no such sub-folder for it.

Using the ‘Newsletters’ Module as an example, the Module itself is located in wp-content/plugins/newsletter/emails and its themes in wp-content/plugins/newsletter/emails/themes (I know, it’s not coherent to call tghe folder “emails” while the module is named “newsletters”, but to keep the compatibility sometime compromises must be accepted…).

How to add themes to a module

Newsletter provides a merge and override system for themes.

Just to explain what this is, I’ll use an example based on the ‘Newsletters’ Module. When Newsletter looks for themes for ‘Newsletters’ Module, it first searches themes inside the natural theme folder, wp-content/plugins/newsletter/emails/themes. Then it scans a second folder at wp-content/extensions/newsletter/emails/themes. The folder wp-content/extensions/newsletter is a parallel version of the original plugin folder, and Newsletter treats both folders as if they were only one folder, by merging the contents of both folders together.

To be more visual, if the folder wp-content/plugins/newsletter/emails/themes contains those themes:

  • default
  • last-post
  • vimeo-like

and the folder wp-content/extensions/newsletter/emails/themes contains

  • my-theme
  • last-post
The system will ends up with a list containing: default, last-post, vimeo-like, my-theme.

What if the theme names conflict? In such cases, they will be a treated as a single theme. So while Newsletter is searching for theme files, it will first look inside the custom folder (wp-content/extensions/newsletter/emails/themes) and then in the original one (wp-content/plugins/newsletter/emails/themes). This is technically called “override”.

This technique is very commonly used by CMS systems to enable users to redefine standard behaviors whilst retaining the base system update-safe (since the custom files are never overwritten by upgrades). This merging is only a part of the whole.

An example may worth thousands of words.

The default theme has a ‘theme-text.php’ (we will see its meaning later) which produces a plain text content. Suppose the default email theme is all you need on your blog, but you’re not satisfied by the textual part generated by the original theme-text.php file. You can override the file creating the folder wp-content/extensions/newsletter/emails/themes/default and putting your theme-text.php version of the file there. As you can note, that folder is the parallel of wp-content/plugins/newsletter/emails/themes/default, the folder for the default theme.

When Newsletter will be updated, the custom file is preserved because it is out of the Newsletter folder (which is deleted by WordPress during the upgrade process).

Finally, what is a theme and how is it structured?

Technically a theme is a folder inside the themes folder of a module either inside the plugin installation folder or its parallel folder as seen above. That folder gives the name to the theme and it’s mandatory for it to contain the theme.php file. Other optional (but recommended) files are the theme-text.php and the theme-options.php.

Theme CSS styling

As well as the basic structure and logic, the new version of Newsletter is different from previous versions by the fact that it no longer uses a ‘style.css’ file. I decided to remove it because themes now can have specific configuration options and sometime the CSS elements can be generated from configuration. So the style must now be embedded in the theme.php file itself. But remember that <style> section are most of the time ignored or not so well interpreted by email clients.

Anyway, emails cannot usually refer to external CSS, hence styles must always be embedded.

A second reason is that the resulting HTML is now fully stored on the database since the delivery engine is now “unrelated” to the module which generated the message (and how it generated it).

Important CSS Note:

The CSS part of a theme must be uniquely identified by only one block of <style></style> tags. Newsletter only extracts the CSS once from the first set of <style> tags when passing the style information to the visual editor. Hence any other <style> tags elsewhere in the file will not be accessed.

Theme files: Nuts and Bolts

The theme.php

The main theme file, and the only one required, must be named theme.php and is the one used to generate the HTML part of your emails. It is a normal PHP file that, when it runs, it must produce an HTML page. This file benefits from some PHP variables that are prepared by Newsletter that can be used to create dynamic content. These include:

  • $theme_options – is an associative array with theme options. Each key on this file must be prefixed by “theme_”. Theme options, as we see later, contains everything the theme needs to generate it’s content as configured by the user. A theme can have no options or tons of options.
  • $newsletter – is a reference to a Newsletter class instance for who need advanced functions.
  • $theme_url – is the URL to the theme base folder and should be used to refer images. Pay attention that if a theme is the merge of a packaged theme and a customization with its parallel folder, the URL point the theme folder inside the plugin, not the parallel version.
  • $theme_subject – is a variable you can use to “pass up” an alternative subject to the theme caller. It’s used to “suggest” a subject on newsletter composer and to define the subject on ‘Feed by Mail’ module for automatically generated emails.

theme-text.php – for plain text version

This file acts identically to theme.php but must generate a plain text that will be used as textual (alternative) part of messages. As you may already be aware, Newsletter sends its messages in both HTML and plain textual versions. This was a big change to previous versions, and it is an attempt to respond to the many requests I received to help reduce the problem of ‘spam’. It is uncertain as to how effective this actually will be, but at least it will not do any harm, and could very possibly help reduce this issue to some extent.

theme-options.php – code your own set of custom options

This is the biggest news. Themes can have their own options, from colors to text, from ‘categories’ to ‘number of posts to include’. Creating an options file does require some coding, but you can start from pre-packaged theme option files, to get you a quick start from which you can customise your changes.

Custom ‘Theme Configuration Panel’

Newsletter has a special class named ‘NewsletterControls’ which enables you to create input elements (text, textarea, list of categories, etc). Within theme-options.php, an instance of this class is available in the variable $controls and should be used to build the theme configuration panel.

Important You must prefix all theme options with “theme_”: this way Newsletter can recognize them and store theme separately and linked to their theme.

How to create a new theme

For ‘Newsletters’ Module, it’s pretty simple:

  1. choose a name, for example “mytheme”
  2. create the folder “mytheme” in wp-content/extensions/newsletter/emails/themes
  3. copy the file of the default theme (wp-content/plugins/newsletter/emails/themes/default)
  4. you now have a working theme, start to modify it

For other modules, the procedure is the same. You just have to go to the correct folder location for that specific folder (see above).

Migrate from old themes

In older versions of Newsletter, custom themes were stored inside wp-content/plugins/newsletter-custom/themes and some of them relied on a couple of variables containing the ‘latest posts’. However, the new version no longer works that way, because the composer is different as you now cannot set ‘categories’ or ‘number of posts’ while composing.

The best approach is to create a new theme with similar options and re-code the theme a little. The main difference from old themes is how to extract posts and how to cycle them. Since the composer no longer offers a method of choosing categories, when migrating a theme you will have to provide a theme options file where ‘categories’ can be chosen.

Themes with the latest posts

A theme can generate a simple “static” page or embed the latest posts of the blog. It’s up to the theme to offer options to selected the post categories, the maximum number of posts and so on. Assuming a theme needs to create a post list it should:

  • extract the posts
  • cycle through them

The post cycle

While a WordPress theme uses the ”while have_posts(), the_post()” kind of loop on a Newsletter theme it’s better to use the combination of ”get_posts()” and “setup_postdata()”. That avoids the sticky posts, at least. The packaged themes, specially the default theme, is internally documented.

The cycle should look like:

<?php foreach ($posts as $post) { setup_postdata($post); ?>

The post list

The post list depends on the options a theme exposes to the user. Usually a theme should offer at least the selection of the categories and the maximum number of posts to display.

To extract the posts, just add to your theme the code you find on theme-1, which looks like:

$filters = array();
// Maximum number of post to retrieve
 $filters['showposts'] = (int)$theme_options['theme_max_posts'];
 if ($filters['showposts'] == 0) $filters['showposts'] = 10;
 // Include only posts from specified categories. Do not filter per category is no
 // one category has been selected.
 if (is_array($theme_options['theme_categories'])) {
 $filters['cat'] = implode(',', $theme_options['theme_categories']);
 }
// Retrieve the posts asking them to WordPress
 $posts = get_posts($filters);

As you can see, adding new options to your theme, you can totally change how the theme works and a study of the WP_Query class (of WordPress) should be the starting point to discover all type of filter available.

Custom post types

Many themes add new post types to WordPress. For example: product, topic, reply, forum, movie, and so on. WordPress only extracts its own (which are of type “post”. Anyway the filter for the get_posts() function can be changed to extract any kind of posts.

$filters['post_type'] = array('post', 'topic');

The above example extracts all standard WordPress ‘posts’ as well as bbPress topics.

Themes for version 2.5 (free and pro)

Themes for version 2.5 work in the same way as themes for version 3.0, but they must be located in a different folder. To create a custom theme you should:

  1. create the folder “newsletter-custom” inside “wp-content/plugins”
  2. create a folder name “themes” inside “newsletter-custom”
  3. copy one of the provided theme folder from newsletter/themes or newsletter-pro/themes inside the previous folder
  4. rename it with you preferred name (no spaces and use only letters and numbers)

That new custom theme should suddenly appear on the ‘composer’ and then you can change it as you prefer. The themes that come provided to you with Newsletter are all well ‘commented’ so that their code is easier for you to modify.

Happy coding!