https://github.com/posthtml/posthtml-mso
Makes writing Outlook conditionals in HTML emails easy.
https://github.com/posthtml/posthtml-mso
conditionals email-templates html html-comments html-email mso outlook outlook-conditionals posthtml posthtml-plugin
Last synced: 7 months ago
JSON representation
Makes writing Outlook conditionals in HTML emails easy.
- Host: GitHub
- URL: https://github.com/posthtml/posthtml-mso
- Owner: posthtml
- License: mit
- Created: 2020-04-09T17:12:29.000Z (almost 6 years ago)
- Default Branch: master
- Last Pushed: 2024-10-21T08:52:37.000Z (over 1 year ago)
- Last Synced: 2024-10-29T21:06:06.652Z (over 1 year ago)
- Topics: conditionals, email-templates, html, html-comments, html-email, mso, outlook, outlook-conditionals, posthtml, posthtml-plugin
- Language: JavaScript
- Homepage:
- Size: 1.34 MB
- Stars: 21
- Watchers: 4
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- Funding: .github/FUNDING.yml
- License: LICENSE
Awesome Lists containing this project
README
Outlook Conditionals
Makes it easy to write Outlook conditionals in HTML emails
[![Version][npm-version-shield]][npm]
[![Build][github-ci-shield]][github-ci]
[![License][license-shield]][license]
[![Downloads][npm-stats-shield]][npm-stats]
## Introduction
Writing Outlook conditionals in HTML emails is gross:
```html
```
It gets even worse when you need to target _specific versions_:
```html
```
This PostHTML plugin simplifies the way you write Outlook conditional comments:
```xml
Show this in all Outlook versions
```
Like, really simple:
```xml
Show in 2007, 2010, 2013
```
## Install
```
npm i posthtml-mso
```
## Usage
```js
import posthtml from 'posthtml'
import mso from 'posthtml-mso'
const options = { /* see options below */ }
posthtml([mso(options)])
.process('Show in Outlook 2013')
.then(result => console.log(result.html))
//
```
## Syntax
The plugin provides two ([customizable](#options)) tags:
1. ``
2. ``
### ``
This will output the content inside it, wrapped in an Outlook conditional comment.
The conditional is created based on the Outlook version(s) you need to target, which you can define inside special attributes ([documented below](#attributes)).
Using the tag with no attributes will target all Outlook versions:
```xml
Show this in all Outlook versions
```
Result:
```html
```
### ``
This tag will basically hide content from all Outlook versions:
```xml
All Outlooks will ignore this
```
Result:
```html
All Outlooks will ignore this
```
### Attributes
To define which Outlook versions you are targeting, you can use one of the following attributes:
- `only` - show only in these Outlook versions
- `not` - show in all versions _except_ these
- `lt` - all versions before this (not including it, i.e. _lower than_)
- `lte` - all versions before this (including it, i.e. _lower than or equal to_)
- `gt` - all versions after this (not including it, i.e. _greater than_)
- `gte` - all versions after this (including it, i.e. _greater than or equal to_)
### `only`
Show the content only in this Outlook version:
```xml
Show only in Outlook 2013
```
Result:
```html
```
It also supports multiple, comma-separated versions:
```xml
Show only in Outlook 2013 and 2016
```
Result:
```html
```
Note: targeting Outlook 2016 will also target Outlook 2019 (see [gotchas](#gotchas)).
### `not`
Show content in all Outlook versions except the ones specified.
```xml
Don't show in Outlook 2013
```
Result:
```html
```
You can also specify a comma-separated list of versions:
```xml
Don't show in Outlook 2013 and 2016
```
Result:
```html
```
### `lt`
Show in all versions before this one, excluding it:
```xml
Show in all Outlooks before 2007, excluding it
```
Result:
```html
```
### `lte`
Show in all versions before this one, including it:
```xml
Show in all Outlooks before 2007, including it
```
Result:
```html
```
### `gt`
Show in all Outlook versions after this one, excluding it:
```xml
Show in Outlook 2010, 2013, 2016, 2019
```
Result:
```html
```
### `gte`
Show in all Outlook versions after this one, excluding it:
```xml
Show in Outlook 2007, 2010, 2013, 2016, 2019
```
Result:
```html
```
## Combining Attributes
You can combine the `lt`, `gt`, `lte`, and `gte` attributes if you need to target multiple versions with higher accuracy.
```xml
Show in 2007, 2010, 2013
```
Result:
```html
```
## Gotchas
There are some cases that might not work as you'd expect.
### Outlook 2019
Outlook 2019 uses the same version identifier as Outlook 2016 - `16`.
Because of this, if you target either of them you will be targeting them both. Currently there is no way around this.
### Duplicate Attributes
Consider this example:
```xml
Show in 2007, 2010, 2013
```
Since duplicate attributes are discarded when parsing, `gt="2007"` will not be taken into consideration.
The result will be:
```html
```
### Unknown Versions
Made a typo like this?
```xml
Target Outlooks before 2007
```
If an unknown Outlook version is specified, the plugin will skip the tag and return its contents:
```html
Target Outlooks before 2007
```
Hopefully, we won't need this plugin by then...
## Options
### `tag`
Type: `string`\
Default: `outlook`
The name of the tag you want the plugin to use. Will be used for both available tags.
For example:
```js
import posthtml from 'posthtml'
import mso from 'posthtml-mso'
const html = `
Show in Outlook 2013
Hide from Outlook
`
posthtml([mso({ tag: 'mso' })])
.process(html)
.then(result => console.log(result.html))
//
// Hide from Outlook
```
[npm]: https://www.npmjs.com/package/posthtml-mso
[npm-version-shield]: https://img.shields.io/npm/v/posthtml-mso.svg
[npm-stats]: http://npm-stat.com/charts.html?package=posthtml-mso
[npm-stats-shield]: https://img.shields.io/npm/dt/posthtml-mso.svg
[github-ci]: https://github.com/posthtml/posthtml-mso/actions
[github-ci-shield]: https://github.com/posthtml/posthtml-mso/actions/workflows/nodejs.yml/badge.svg
[license]: ./license
[license-shield]: https://img.shields.io/npm/l/posthtml-mso.svg