Using Expectations gives you even more control over how fields and editables within your Design System are used.
When building an Email Design System you'll want to make sure that the teams creating emails are using each field in the right way. For example, ensuring they don't use too much text for a headline or that they don't leave a particular field blank. You can use Expectations to add this level of control to your Design System.
This means that you can tell Taxi exactly what you want from the different parts of your Email Design System, so you can do more to stop emails being exported with content missing or with content you don't want.
Below, there is a placeholder image that has to be changed before the email is exported from Taxi. There is a message in the editor telling you it needs to be changed and there will also be a warning if you try to export this email without changing the image. Therefore reducing the chance of this email getting sent out with a placeholder image.
To find out more information about how this will appear in your Taxi account, have a look a this help article.
To add this to your code, you use the expect attribute on fields or editables. You can use more than one Expectation per field or editable. To do this, separate them with semicolons, similar to CSS.
<editable rich name="text" default="lorem ipsum" expect="must-change;no-blank;copy-limit:30"> </editable>
The values you can use in this attribute are:
If this is applied then the field has to be changed before the email is exported. For example, if you have Lorem ipsum' placeholder copy, you can use the must-change Expectation to make sure this isn't in the email when it is exported.
This expectation can also be used on dropdown and multivalue dropdown fields.
The field must be changed before the email can be exported.
<editable name="text" default="lorem ipsum" type="text" expect="must-change"> </editable>
This means that the field has to have a value input before the email is exported, it can't be left empty. This Expectation can be used on all fields.
<editable rich="" name="text" default="lorem ipsum" expect="no-blank"> </editable>
This is similar to the must-change attribute but it means that the fields in the non parent version of a mailing must not be inheriting their content from the parent version. This can be used on all fields.
<editable rich name="text" default="lorem ipsum" expect="must-translate"> </editable>
You are able to set a limit on the number of characters that can be used in rich text fields. The field will show a warning when the copy limit is exceeded and you won't be able to export the email.
Unlike the above Expectations, which are just a single word such as no-blank or must-change, with this Expectation you can define an exact copy-limit for any rich text field.
<editable rich name="text" default="lorem ipsum" expect="copy-limit:20"> </editable>
This Expectation can be used in alignment fields. It enables you to define which alignment options you want to be available in the editor. For example, if you only wanted the choice of left and centre alignment but not right.
The allowed values are:
<field name="alignment" type="align" expect="values:left centre"></field>
This Expectation can only be used on href fields. It can't be used on editable tags, only field tags. If you use this then the link in this field has to start with https, if the link starts with anything else, such as http, you'll see this warning message.
Add https-only to the expect attribute to use this expectation.
<field name="link" type="href" expect="https-only"></field>
Set the minimum value that can input to a number field.
<field type="number" name="width" expect="min-value:10"></field>
Set the maximum value that can input to a number field.
<field type="number" name="width" expect="max-value:10"></field>
The must-change, no-blank and https-only expectations are also supported on fields in rich-editable-style tags.
<rich-editable-style name="link">
<field name="href" label="Link" type="href" expect="no-blank;"></field>
<a replace-href="{{href}}" style="text-decoration:none;color:#000000" replace="{{rich.selection_text}}"></a>
</rich-editable-stlye>
There are several attributes that can be used in a field tag that control what options are available in that field, such as allow-custom on a colour field or allow-styles on a rich text field. These existing attributes can also be used as Expectations.
This attribute is used on dropdown colour fields when you have a set list of colours to choose from but you also want to input a custom hex code if needed. For example, allow-custom="true". You can include this in the expect attribute and the allowed values are:
If you include just allow-custom on it's own, this is the equivalent of allow-custom:true.
<field type="colour" name="colour" expect="allow-custom:true"></field> <field type="colour" name="colour" expect="allow-custom"></field>
Allow-none can be used on image fields and will give you the option to not include an image when there is an image field in your Design System. This can be used as a value in the expect attribute instead of as an attribute itself. You can also use allow-none:true to have the option to not include an image.
<field type="src" name="image" expect="allow-none"></field>
This is used to define what styles you want available on individual rich text fields. For example, allow-styles="bold italic". It can be used in the same way in the expect attribute with the styles separated by a space.
The allowed values are:
<field type="rich" name="text" expect="allow-styles:bold italic"></field>
This can be used on colour fields to define what formats can be used, such as hex, rgb or rgba. The default is hex if you don't define a format and you can use one format in any colour field.
The allowed values are:
<field type="colour" name="colour" expect="format:rgb"> </field>
When the expect attribute includes something which is also set with a custom attribute, then you will see a warning when you upload your HTML. For example, if allow-custom is set as an attribute but also as part of the expect attribute.
If the expect attribute contradicts another attribute in that field then there will be an error message when you upload your HTML. For example, allow-custom="true" and expect="allow-custom:false" in the same field would cause an error message.
Images are one of the most powerful design elements in an email marketers' toolkit — but even the most beautiful image can't shine if it's uploaded in the wrong format, causes slow load times, or gets distorted. Translate your guidelines and email marketing best practices around imagery, into Taxi by adding the following set of Expectations to your image src fields and stop any mistakes before they happen.
Use the max-file-size Expectation to ensure that images never exceed a certain file size. Whether you're using static images or animated GIFs, setting a limit for your files sizes helps make sure that your imagery isn't causing slow load times. File sizes must be set in kb, so if you'd like to set a file size limit of 1MB for your images, here's how that would look:
<field type="src" name="image" expect="max-file-size:1000"></field>
Specify what image file formats are supported within your Email Design System with this Expectation. If you'd like to allow multiple image formats, let's say gif, jpeg, and png file types, you can separate them with a space like this:
<field type="src" name="image" expect="format:gif jpeg png"></field>
With the aspect Expectation you can specify what aspect ratio requirements your images must meet. For example, this is how you'd make sure that all uploaded images have a 16:9 aspect ratio.
<field type="src" name="image" expect="aspect:16by9"></field>
Use the width Expectation to make sure all images are exactly as wide as you've specified. The width is set in pixels.
<field type="src" name="image" expect="width:600"></field>
Use the height Expectation to make sure all images you add to your emails are exactly as high as you've specified. The height is set in pixels.
<field type="src" name="image" expect="height:400"></field>
Use the min-width Expectation to make sure all images are at least as wide as you've specified. The min-width is set in pixels.
<field type="src" name="image" expect="min-width:600"></field>
Use the max-width Expectation to make sure all images don't exceed the width you've specified. The maximum width is set in pixels.
<field type="src" name="image" expect="max-width:700"></field>
If you'd like to provide a range for an allowed image width, you can combine the two attributes. For example, here's how you'd set an Expectation that requires all image to be between 600 and 700px wide:
<field type="src" name="image" expect="min-width:600; max-width:700"></field>
Use the min-height Expectation to make sure all images are at least as high as you've specified. The min-height is set in pixels.
<field type="src" name="image" expect="min-height:600"></field>
Use the max-height Expectation to make sure all images don't exceed the height you've specified. The maximum height is set in pixels.
<field type="src" name="image" expect="max-height:700"></field>
You can use the same approach as above, and use min-height and max-height together to create a range of heights that the image can be.
All of the width and height Expectations are related to the size of the image file or url you add to your email, not the number you add to the width or height fields for an image.
With image fields there are also two built in expectations that will cause warning messages when adding an image into an email. These are not recognised in an Email Design System.
You will see an expectation warning if an image you try to add to your email contains a CMYK colour profile. A CMYK colour profile can affect how the colours in the image render in Taxi and in email clients.
You will see an expectation warning if you add an image to an email that contains an exif-rotation tag. This could make the image appear upside down in some email clients.
You will only see these warnings when using the url option to add an image into your email. When uploading a file from your browser, Taxi will automatically fix the colour profile and exif-rotation if needed.
If you accidentally input an image url into a href field in the editor you will see a warning that reads 'It looks like this link is pointing to an image'.
As well as setting expectations on fields to control how they are used, you can do this on modules too. If you want to limit the number of times a module is used or stop certain modules being used together then you can add an expect attribute to the module tag.
These expectations are only valid on module tags.
Limit the number of times a module is used in an email.
<module name="fullwidthimage" label="Full width image" expect="max-usage:3;">
In this example, the Full Width Image module can only be added to the email three times. You will see this warning in the module if you add it a fourth time:
Stop certain modules in the Email Design System being used together. If you didn't want the Full Width Image module to be used with a 'Side by Side' module we could use the following expectation.
<module name="fullwidthimage" label="Full width image" expect="dont-use-with:modulezones.content.modules.side_by_side;">
In the dont-use-with Expectation you need to include the following:
- Modulezones
- The name of the modulezone the module you are targeting is in.
- Modules
- The name of the module you are targeting
In this expectation you need to use the names in the EDS, not the label.
You can use this across modulezones, so you could stop a module being added in the header modulezone if a module in the body modulezone is already included in the email.
You can also use both expectations together. Like all other expectations they need to be separated by a semicolon.
<module name="fullwidthimage" label="Full width image" expect="max-usage: 3;dont-use-with: modulezones.content.modules.side_by_side;">
You will also see a warning before adding the module to the email, when viewing your list of modules.
All of the above expectations have some predefined text that appears in the editor when they are not met.
It is also possible to include your own custom messages here instead.
These can be set in the EDS or brand settings. There is an expectations tab where you can set these.
These set the messages for the whole Email Design System. For example, if you have 20 fields with a no blank expectation, whatever you add here will be applied to all of those fields. These can be used in an EDS and a brand.
If you want to override these with a message specific to one field, you can also add an expect-messages attribute to the field tag.
<field name="cta_text" type="text" label="CTA Text" expect="no-blank;" expect-messages="no-blank: This field can't be blank as we need to have a CTA in this type of module;"></field>
You can include as many messages in one field as you need.
If you don't use any custom messages then the standard Taxi message will show in the editor.
These Expectations can be used on editables or fields. If used on an editable, all fields within that editable will use that Expectation. If used on a field, the Expectation will only apply to this field, and if that field is within an editable that has a different Expectation, the field Expectation will take precedence.
Not all Expectations can apply to all fields, for example you can't have a copy limit on a colour field. If a field is inside an editable that uses an Expectation that can't be used, the Expectation will be ignored for that field. If no fields in the editable can use the Expectation then you will see a warning message when you upload your HTML.