Template Creation

Description of an emailing template

An emailing template is a compressed file (in zip format) having like extension .htmlzip.

A template file must contain :

an HTML file,
image files (optional).

The file tree is free.

HTML file structure

To be used in the Wedia editor, the HTML file structure of the template must be valid. In order to guarantee the readability of the e-mails in the different e-mail programs, it is important to respect the rules prescribed by the supplier through which the mails will be send to the users.

There is a very useful site to validate and correct templates emails or at least alert you to bad practices and who you are will limit the problems to exploitation: http://premailer.dialect.ca/

Use of CSS in the HTML file of the template

Although very [.label-danger]# strongly discouraged#, the use of CSS style sheets is nevertheless possible under certain conditions. Make sure that your email provider will be able to manage them and eventually retranscribe them for HTML readers that do not manage CSS.

It is also possible to describe text style sheets which can be made available to users in order to create their emails in the editor’s WYSIWYG editors.

It is strongly discouraged to bind external sheets. Prefer the inclusion of CSS class definitions in a <style> tag in the <head> element of the HTML template to ensure a better compatibility.

Note

Since version 10.5.0 WEDIA WXM no longer transforms CSS styles in inline styles in the export files in order to avoid the modifying of the email behavior. It is therefore important to inquire with the email broker in order to know what it recommends in the case of CSS use and whether it realizes itself this transformation at the time of sending emails.

More generally, it is important to know good practices and rules of use for style sheets according to customers targeted email, there are excellent articles on blogs and support pages:

litmus and mailchimp just to name a few, to get some ideas of the state of the art on the subject.

Templates responsive design

The responsive design templates rely on CSS support in emails. To use them it is therefore necessary to be sure that the end user who will read the email is able to read it correctly. To date many email readers do not support CSS or only partially; so these readers will not display a responsive email from in the correct way. At the mobile phone level only a few support officially responsive design emails:

iOS Mail App,
Android 4.x Email/OEM App,
Windows Phone 7.5,
BlackBerry OS7 + Z10

The following applications do not support responsive design emails

iPhone Gmail app,
iPhone Mailbox app,
iPhone Yahoo! Mail app,
Android Gmail app,
Android Yahoo! apt,
Blackberry OS 5,
Windows Mobile 6.1,
Windows Phone 7,
Windows Phone 8

Source: https://litmus.com/blog/the-how-to-guide-to-responsive-email-design-infographic)

Definition of an editing area

In a template it is possible to edit the content in several ways:

directly modifying the text
dragging and dropping text content onto a text box
dragging and dropping image content onto an image area
dragging and dropping complex content (composed of several properties from a content object) on a group of editable zones

To be a candidate for modification, an HTML element must have an attribute named data-wxm-editor-zone (the value of this attribute is optional).

The attribute data-wxm-editor-zone allows to declare to the WXM engine that the element can receive edition information either for the live user, or automatic (made by the engine). The edition information is described by the other attributes detailed below.

Text editing

To offer users the ability to edit text via the email editor it will be advisable to add the attribute data-wxm-editor-zone-editable="true" on HTML elements that you want to make editable.

By default an editing area will always be uneditable by the user.

The attribute can be placed on any element HTML DIV, TD, P, SPAN, H2, etc… However, it is recommended to place this attribute on an HTML block element such as DIV or TD; indeed these elements are likely to receive in their breasts any other HTML elements that could be added by the user, which cannot be done in a P or SPAN element for example.

Define styles for editing

It is possible to define lists of styles that can be proposed users when editing content via the WYSIWYG editor. The list of styles must be defined in the data-wxm-editor-zone-styles attribute according to the styles present in the email.

All CSS classes that can be used in the template should be described to define on the target zones the styles at their disposal. For example

<html>
  <head>
      <style>
      p.text{
        font-size:12px;
      }
      h2.title{
        font-size:18px;
      }
      h3.subtitle{
        font-size:14px;
      }
      </style>
    </head>
<body>
  <div data-wxm-editor-zone="A" data-wxm-editor-zone-editable="true" data-wxm-editor-zone-styles="title,text">Editable content</div>
  <div data-wxm-editor-zone="B" data-wxm-editor-zone-editable="true" data-wxm-editor-zone-styles="subtitle,text">Another editable content</div>
</body>

In this example we described three styles: p.text, h2.title and h3.subtitle.

Both zones will allow the user to use the styles: The title and text for zone A and `subtitle and text for zone B.

Note that for each style the element to which it should apply is declared. This is not necessary but nevertheless recommended. If the element is not specified the editor will allow it to use these styles by default on P elements (if the content to be edited is in an HTML element of type block different from P) or on SPANs.

As far as possible, always prefer the declaration of the element in the styles declaration in order to best control the HTML generated by the publisher. Note: before the 10.5.0 version of the engine, style names cannot contain capital letters.

Drag and Drop content

By default all output fields with the attribute data-wxm-editor-zone-editable="true" can be candidates to receive content from the Content Management tabs by drag and drop.

IMG elements with this attribute will be able to receive image content from the DAM or present in the image content library WXM (galleryelement) or downloaded by the user.

Text elements (DIV, TD, etc…) can receive HTML content or text from any WXM content object.

In the case of an image, it is the src attribute of the image that will be updated by WXM, otherwise it will be the content of the element that will be updated with the first HTML property of the registered object (or the property with the wxm_dtpmanager_maintext).

examples :

If the HTML element is an image then only drag and drop of image elements from the DAM will be allowed.

<img data-wxm-editor-zone data-wxm-editor-zone-editable="true" src="URL_OF_THE_IMAGE" alt="" border="0" />

If the HTML element is not an image the user will be able to modify the HTML content of this element or drag and drop text content onto it.

<div data-wxm-editor-zone data-wxm-editor-zone-editable="true" >un contenu HTML à modifier</div>

When dragging and dropping the editor will attach the HTML element to the dropped content on the latter. So if the content is subsequently modified outside the editor the email will be updated with the new values of this content.

Drag and Drop structured content

It is possible to upload structured content that updates several HTML elements in a single removal. For example, we can update with a single gesture the title, one or more images, one or more texts in depositing content directly in its reception area.

In order to do this, it will first be necessary to link together all the elements constituting the structured content via the attribute data-wxm-editor-zone-group. This will identify all elements with the same attribute for example: data-wxm-editor-zone-group='article'

Each HTML element will then be attached to a key that will allow to find the association between the property of a content object and this HTML element. The content keys must be described as explained in this document: Creation of the repository on Wedia CrossMedia. The standards of content are common between emailing and print.

HTML elements will be assigned the repository keys in the data-wxm-editor-zone-refkey on all zones defined by data-wxm-editor-zone-group.

Exemple

Association of HTML elements to contents in the system

When WXM content is dropped on an email the WXM application links the HTML element to a property of that content object. In the case of structured content the relationship is given through the key in the content repository, if not by the nature of the object and the receptacle (image or text).

The relationship between the HTML element of the email and the WXM content is achieved by three attributes bias that will allow the engine to update the content email if needed. These attributes are:

data-wxm-binder-objtype	to link the HTML element to a content object
data-wxm-binder-objid	that links the HTML element to an instance of the content object
data-wxm-binder-objpath	to link the HTML element to a property of the instance of the content object

Important notes regarding the placement editing areas

The editing areas can be placed on almost any HTML element. However, there are still a few exceptions and you will not be able to define an editing area on the following HTML tags:

object
video
canvas
table
tr
embed
hr
ol
ul

Generally speaking, it is highly recommended to ensure that you define HTML edition fields on DIV elements (preferably) allowing to receive any HTML content, especially when the area is supposed to receive content by drag and drop. Note that if it is not recommended to define editing areas on other types of elements that is still possible.

TD Elements are also likely to receive any content HTML however it is not recommended to use them in your templates if your users access the email editor via a browser Microsoft Internet Explorer (any version). IE does not allow Conduct online publishing on TD elements.

When an element has been declared as an editing area it will be possible to modify its HTML content via the emailing editor. In the particular case of the img element it is the src attribute that will be modified and not its content, the img element having no content.

Attribute editing

From version 10.5.1 it is possible to modify the attributes HTML elements located outside the standard output fields. The attribute editing allows for example to leave the possibility to the user to change the URL of a link.
In order to activate this feature it is necessary to set an attribute on the element (data-wxm-editor-zone) and list the attributes in a data-wxm-editor-zone-editable-atts attribute the attributes one wants to make it editable by the end user.

For example, data-wxm-editor-zone-editable-atts="href,title" placed on an element a will allow the user to modify the href and title attributes of the link.

If more than one HTML element has this attribute output information are nested and the user clicks on the lowest element (in the DOM) then the edit window will allow him to edit all the attributes of all elements by placing each different HTML element in an editing tab.

Definition of structural change fields

It is possible to define zones that will allow users to duplicate/delete content blocks or move them between them.

Repeatable blocks

Repeatable blocks allow the user to duplicate areas of or delete them. To do this there is an attribute that allows to declare the blocks as repeatable, these are the attribute data-wxm-editor-repeatable.
If it is true then when the user selects the block with the appropriate tool a menu will allow him to duplicate or delete this block.

In case of duplication the copy of the block will be inserted just after the copied block in the DOM. If there are editing fields in the copy and they are linked to a content then they will be detached from these contents (the data-wxm-binder-objtype, data-wxm-binder-objid attributes and data-wxm-binder-path will be emptied).

Movable blocks

Movable blocks allow the user to reschedule content areas between them. To do this there is an attribute that allows to declare the blocks as movable, it is a question of the data-wxm-editor-movable attribute.
If it is true then when the user "grabs" with his mouse the block after selecting the moving tool in the menu it will be able to move the block before or after its direct brother elements.

Important note

Analysis functions for email opening, clicked link analysis and hosting of embedded resources are dependent on the mail router. The router has an action to rewrite links and path to resources to allow a follow-up of the actions of the recipients and the distribution of the images, specific to its technology. The WEDIA CrossMedia platform does not provide no default transformation of links and resources.

Similarly, email customization actions for example to insert the name of the recipient or to condition the display of a block of content in of the recipient’s segment in the body of the email are also the same functions provided by the mail router. The exploitation of these functionalities directly in the newsletter editor is not expected at this stage.

Image size management

When drag/drop image type content within an email the editor will replace the src attribute of the corresponding HTML image element with the new image source.

The actual image placed by the user may not have the same dimensions than the image block provided in the email template used.

If the model contains the width and/or height attributes it could even be the image is distorted because the email reader will resize the image to these values.

Fortunately it is possible to control the display of images from several ways :

by defining automatic resizing rules
by letting the user define himself the sizes to use
by creating an image variation respecting the constraints given in the email

Definition of automatic resizing rules

To allow the email reader to intelligently resize the image without distorting it one will proscribe in the model of email the use of the attributes width and height on img elements (as well as in the style).

Indeed these attributes require the reader (browser) to resize the image to the dimensions fixed on the element.

So if we specify these attributes to the values height=200px and width=200px then then any image placed in the block will be displayed at dimensions 200x200 and whatever the real dimensions of the image, thus risking to distort the image.

By placing an image of 1900x900 on a block having the defined attributes above we obtain a rendering equivalent to the example below.

To avoid these distortions and allow the player to resize the image in the right proportions as foreseen by the email model we will use the information max-width and max-height which will give the reader the maximum values that it can use to resize the image without the distort.

Concretely this comes back in the HTML of the template to replace the attributes following width and height

by

Leave the user modify the width/height attributes

In order to allow the user to set the width and height so that it can adapt them to the image it is enough to make these attributes can be modified via the editor.

To do this it is enough to add at the model level the attribute data-wxm-editor-zone-editable-atts='height,width' on the image element.

The presence of this attribute makes the attribute editor available (tool represented by the symbol </> in the toolbar); when the mode is enabled then all HTML elements with that attribute become and access the attribute editor that will allow you to here to set the values of the width and height attributes of the image:

In our case it will be enough to set the value of the height attribute to 150px so that the image is no longer distorted.

Modify the image so that it respects the constraints of the model

By accessing the image editor (renditions) located on the image file via the link Preview of the image in the project folder (search in the project)

then by clicking on the Edit button

and finally on the button Modify located near the thumbnail in the form publishing

The rendition tool will allow to crop the image so that it is placed without distortion in the email

After having being saved in the system the email will be returned with the new image