ePublishing Knowledge BaseePublishing Knowledge Base Creating and Sending eNewslettersSetting up a default newsletter template with shortcodes

Setting up a default newsletter template with shortcodes

Shortcodes provide a simple and powerful shortcut to embed content, and when combined with our newsletter tools, you can gain a lot of control over the newsletter's layout. We recommend a basic layout right out of the box, but you can customize it much further. This article explores the building blocks for your newsletter and the options available to you.

Out of the box

We'll start by breaking down each section, to find out how it's setup by default and then options that are available to you. Everything is controlled by Newsletter Rendering Options, Editorial Content, Content Zones, and the Menu Manager.

In the next few sections we'll recreate the above design.

The navigation is setup by defining the name of the menu in the rendering option called "menu.name". The name of this menu will match the name of your menu in the Navigation Manager.

You will first upload your logo to the Media Manager. Copy and paste your uploaded image's URL to the rendering option "logo.path". This URL should not include the domain name, that is handled from the template. The next rendering option you will need to set is the "logo.width". The value should be a number followed by px.

Pre-header

The pre.header is optional and is the line of text that the user will see in their inbox beside the subject line. It does not actually appear anywhere in the body of the newsletter.

Articles

Let's use our first shortcode. There are several attributes a shortcode can accept that are unique to each shortcode. In the following example, we'll use columns, total, and template.

Note: Mixing the use of shortcodes with and without the taxonomy attribute requires that you manually manage the order of articles associated with your newsletter. Otherwise, using with the taxonomy attribute exclusively will group the articles by taxonomy and ignore the order when articles are associated to the newsletter.

columns: Required. Divides the articles into a single column or two columns.

total: Required. The total number of articles this shortcode will render.

taxonomy: Optional. If you pass a taxonomy ID to this attribute, it will group only articles by that taxonomy to this section. Mixing the use of shortcodes with and without this attribute requires that you manually manage the order of articles associated with your newsletter.

template: Optional. Our default template includes the option to have a background color for any section. This is part of the design, to provide a visual change from other sections —with the goal to improve the overall readability and UX.

images: Optional. Defaults to true. Show or hide images with a true or false value.

image_width: Optional. A default value is different for the single and two column layout.

portrait_image_height: Optional. This is a set height for any portrait image, with a default value of 200.

teaser: Optional. Defaults to true. Show or hide the teaser with a true or false value.

sponsor: Optional. Defaults to true. Show or hide the sponsor with a true or false value.

ad_position: Optional. The numbered position, where the advertisement will render in place of an article. Decrease the total attribute value when placing an ad. Only 1 ad per shortcode can be set.

ad_disabled: Optional. Defaults to false. Hide the ad from showing by setting this to false. This can be useful if you want to hide the ad while maybe you are not serving one, but do not wish to remove the supporting code for now.

[newsletter-articles columns="2" total="2" template="background"]

To set the background color, and border color, there are two additional Rendering Options you can set.

Ad Position Example:

The ad code would be placed between an opening and closing of the shortcode. It should not have any line breaks within the markup, such as before or after the start of a new HTML element.

Note: if content is not placed between the shortcode DO NOT close the shortcode.

GOOD:

[newsletter-articles columns="2" total="3" ad_position="4"]AD CODE HERE[/newsletter-articles]
[newsletter-articles columns="2" total="3"]

BAD:

[newsletter-articles columns="2" total="3" ad_position="4"]AD CODE HERE
[newsletter-articles columns="2" total="3"][/newsletter-articles]

Events

In this section, we will introduce a new shortcode called newsletter-events. This shortcode only has multiple attributes.

taxonomy: Add a taxonomy ID to get only events from a specific taxonomy.

images: True by default. If this value is set to false then the image associated with an event will not display.

template: To customize the background and border template styles for an event section, create a template name and use that in your rendering options. e.g. tmpl.webinars.bg.color

limit: 3 events are displayed by default. Set this attribute with a value of the number of events you want to display.

The purpose of this template variation is to provide some variation in the design, improving the overall readability and appeal to the user experience. We encourage you to take advantage of the variations.

[newsletter-events template="webinar" taxonomy="35" images="false" limit="5"]

Advertisements

In this section, we will introduce a new shortcode called newsletter-ad. This shortcode only has 1 attribute, and then the ad code is placed between the opening and closing of the shortcode.

template: There are currently two template options available: bg-white or bg-none. The former will set a white background in the template behind the ad, to make it appear within the main document. The latter will set the background the same as the document background, making it seem there's a more clear break between sections.

The purpose of this template variation is to provide some variation in the design, improving the overall readability and appeal to the user experience. We encourage you to take advantage of the variations.

disabled: Optional. Defaults to false. If you want to keep the ad code in place but temporarily hide it from rendering, set this value to true.

[newsletter-ad template="bg-white"]AD CODE HERE[/newsletter-ad]

Side by Side Advertisements

In the event that there's a need to place 2 ads side by side, there is a shortcode for that as well. Simply use the newsletter-table shortcode.

The way to distinguish between the left and right columns is by the use of a pipe character ( "|" ) in the middle of the shortcode.

A newsletter-table has two attributes:

Columns: This shortcode will support 2 columns. To set the columns, specify the attribute columns="2". This will create a responsive friendly table. The ads will be side by side on desktop view and stacked on mobile.

Padding: A boolean value of true or false. Defaults to true. A table comes with padding within the table, setting this to false will remove that padding. This may be useful if you nest another shortcode within newsletter-table that has its own padding.

[newsletter-table columns="2"] AD CODE HERE | MORE AD CODE HERE [/newsletter-table]

Rendering Options, Shortcodes, & EC's

Now, the glue that holds this all-together.

At the newsletter level, we have Rendering Options (RO) that allow you to configure certain aspects of the newsletter — which you are already familiar with. We will create new zones within the RO, these are the different sections of your newsletter.

The zones begin after your logo in the design. There's a zone for each section. You can add more zones and name them zone.X, incrementing the value. The limit is currently set to 25.

The blurb shortcode is an Editorial Content zone (EC). The reason for this is two-fold, there's a limit to how many characters can go into this RO field - allowing only simple shortcodes, and a text area like an EC provides more space to edit. You can also place more than one shortcode into an EC.

For example, in the RO zone.1, you would edit this EC by searching for the EC named "newsletter.zone.1". We recommend sticking with this naming convention to prevent any confusion mapping the two together.

Overrides Per Issue

Should you want to override any of these zones on a per issue basis, we've made that possible. On the General page in the Newsletter Manager, create a new zone with the zone name matching the RO name that you want to override. This issue will now use this new zone instead of the one from the ROs.

Other Rendering Options & Final Notes

article.image.width — When the width of the newsletter is modified it's recommended to adjust the image width for articles accordingly.

article.url.params — Appends attributes to every article from the newsletter-articles shortcode. These are attributes that your ESP could parse. Do not begin this value with "?" or "&". e.g. email=@{user_email}@

background.color — A CSS Hex value to change the background color of the overall newsletter.

body.top — Some 3rd party trackers require content to be placed immediately after the opening body html element. Use the blurb shortcode.

facebook.url — Your Facebook URL, when present shows an icon in the layout.

headline.color — The CSS Hex value of your headlines.

layout — This is a base setup requirement, and mostly an ePublishing internal rendering option.

linked.url — Your Linkedin URL, when present shows an icon in the layout.

newsletter.width — Use to override the width of your newsletter. The recommended and default width is 600px.

style.font.teaser — Inline CSS that affects the styles of all teasers.

style.font.headline — Inline CSS that affects the styles of all headlines.

style.footer.left.column —Override the styles on the left column of the footer, ideal for increasing the width if the overall newsletter width has been changed.

style.footer.right.column —Override the styles on the right column of the footer, ideal for increasing the width if the overall newsletter width has been changed.

template — This is a base setup requirement, and mostly an ePublishing internal rendering option. Used to choose the internal default template.

twitter.url: Your Twitter URL, when present shows an icon in the layout.

Contact Call-To-Action Component

contact.link: The link to your contact us page.

contact.link.text — Modify the text of the button.

contact.message: Change the message associated with your contact call-to-action.

contact.style.button — Override the styles for the button.

contact.style.button.link — Override the styles for the button link

contact.style.message — Override the styles for the message.

contact.style.message.link — Override the styles for the message link.

Enable by adding the word "contact" to any zone.

0 Comments

Add your comment

E-Mail me when someone replies to this comment