html-entities-not-email-friendly0.2.9

All HTML entities which are not email template friendly

§ Quick Take

import { strict as assert } from "assert";
import {
  notEmailFriendly,
  notEmailFriendlySetOnly,
  notEmailFriendlyLowercaseSetOnly,
  notEmailFriendlyMinLength,
  notEmailFriendlyMaxLength,
} from "html-entities-not-email-friendly";

// it's object, mapping entity names to numeric equivalents
assert.equal(
  Object.keys(notEmailFriendly).length,
  1841
);

// it's a Set, only listing the bad entity names
assert.equal(notEmailFriendlySetOnly.size, 1841);

// is ≳ email-friendly?
assert.equal(
  notEmailFriendlySetOnly.has("GreaterTilde"),
  true
);
// no, use numeric entity

// is   email-friendly?
assert.equal(
  notEmailFriendlySetOnly.has("nbsp"),
  false
);
// yes, it's OK

§ Purpose

Unlike Web pages, Email templates are sent over SMTP and need to be HTML-encoded.

HTML encoding can be done three ways: decimal (£), hexadecimal (£) and named forms (£).

The named entities can be memorised or recognised more easily than numeric-ones. When we check the template's text, £ is more informative than £. If somebody mistakenly put ¤ you would not tell easily, but &pund; stands out instantly!

The only problem is, not all named entities are supported well across all email clients, in particular, in Windows desktop Outlooks.

This package tells which entities exactly and not supported widely and tells you what to convert them to.

This program exports few different lists:

  • notEmailFriendly — a plain object, key value pairs are like AMP: "amp" — total keys: 1841
  • notEmailFriendlySetOnly — a Set opens in a new tab of only entity names (in correct letter case) — total size: 1841
  • notEmailFriendlyLowercaseSetOnly — an alphabetically sorted Set opens in a new tab of lowercase entity names — total size: 1534

§ API

This package exports a plain object with five keys:

  • notEmailFriendly
  • notEmailFriendlySetOnly
  • notEmailFriendlyLowercaseSetOnly
  • notEmailFriendlyMinLength
  • notEmailFriendlyMaxLength
Key's nameKey's value's typePurpose
notEmailFriendlyplain objectPlain object of all named HTML entities. The key is an entity's name; value is a raw decoded entity. 1841 in total.
notEmailFriendlySetOnlysetA set of all entity names, in correct case, unsorted. 1841 in total.
notEmailFriendlyLowercaseSetOnlysetA set of all entity names, in lowercase, sorted. 1534 in total (because we have AMP and amp for example).
notEmailFriendlyMinLengthnatural numberthe string length of the shortest of all entities, currently hardcoded to 2
notEmailFriendlyMaxLengthnatural numberthe string length of the longest of all entities, currently hardcoded to 31

§ notEmailFriendly

const { notEmailFriendly } = require("html-entities-not-email-friendly");
// it's a plain object of key-value pairs where key is entity name, value is
// decoded numeric entity analogue of it
console.log(Object.keys(notEmailFriendly).length);
// => 1841

The point of plain object notEmailFriendly is to decode the entities.

For example, among the keys you can see:

And: "#x2A53",

This means, named HTML entity ⩓ is not email friendly and should be put as ⩓.

As you noticed, ampersands and semicolons are missing in keys and values (but they're obligatory in HTML code so add them yourself).

§ notEmailFriendlySetOnly

Sets opens in a new tab are awesome because they're fast.

When you import notEmailFriendlySetOnly, it's a Set of only the key names:

const { notEmailFriendlySetOnly } = require("html-entities-not-email-friendly");
for (const entitysName of notEmailFriendlySetOnly) {
console.log(entitysName);
}
// => "AMP",
// "Abreve",
// ...

// another example: check is given entity a valid HTML named entity string?
console.log(notEmailFriendlySetOnly.has("tralala"));
// => false - no "tralala" (if put fully, &tralala;) is not a recognised named HTML entity's name

console.log(notEmailFriendlySetOnly.has("Aogon"));
// => true - yes "Aogon" (if put fully, Ą) is a recognised named HTML entity's name

You must use Set methods: has, size etc on notEmailFriendlySetOnly. It's not an array, it's a set.

§ notEmailFriendlyLowercaseSetOnly

notEmailFriendlyLowercaseSetOnly is also a Set but all values are lowercase and sorted.

The idea is that if you have a named HTML entity and suspect that its letter case might be messed up, you lowercase it and match against this Set. Now, if something is found, do actions matching against plain object keys in notEmailFriendly (aiming to decode to numeric entities), OR matching against a Set with exact case, notEmailFriendlySetOnly (if value is not found, letter case in your entity is messed up).

const { notEmailFriendlySetOnly } = require("html-entities-not-email-friendly");
for (const entitysName of notEmailFriendlySetOnly) {
console.log(entitysName);
}
// => "AMP",
// "Abreve",
// ...

§ notEmailFriendlyMinLength and notEmailFriendlyMaxLength

Their point is to give you guidance how long or short entities can be:

const {
notEmailFriendlyMinLength,
notEmailFriendlyMaxLength,
} = require("html-entities-not-email-friendly");
console.log(
`The shortest length in the set is: ${notEmailFriendlyMinLength} and longest is ${notEmailFriendlyMaxLength}.`
);
// => The shortest length in the set is: 2 and longest is 31.

Keep in mind, length here does not count ampersand and semicolon. For example, Abreve length is 6 characters but in the HTML, it is 8: Ă,

§ In practice

This program allows detergent to automatically switch between named and numeric HTML entities, prioritising on named, if they're supported (acccording this program).

Detergent's competitor, Email on Acid Character Converter opens in a new tab only uses numeric entities. Not to mention, EoA Character Converter ignores invisible characters, which is a liability.

§ Licence

MIT opens in a new tab

Copyright © 2010–2020 Roy Revelt and other contributors

Related packages:

📦 detergent 5.11.10
Extracts, cleans and encodes text
📦 emlint 2.19.1
Pluggable email template code linter
📦 all-named-html-entities 1.3.7
List of all named HTML entities
📦 html-crush 2.0.9
Minifies HTML/CSS: valid or broken, pure or mixed with other languages
📦 string-strip-html 6.1.1
Strips HTML tags from strings. No parser, accepts mixed sources
📦 detect-is-it-html-or-xhtml 3.10.0
Answers, is the string input string more an HTML or XHTML (or neither)
📦 html-table-patcher 2.0.14
Visual helper to place templating code around table tags into correct places