EntityEncoder.md

EntityEncoder

EntityEncoder is used by FauxDOM to encode and decode HTML entities. By setting the entities property, you can specify which entities should be encoded and decoded, allowing for entirely custom entities if you choose.

The EntityEncoder class is accessible as DOM.EntityEncoder, giving access to the static defaultEntities property and allowing you to instantiate the class if you wish to perform entity encoding/decoding on your own.

Table of Contents

• Construction
• Properties
  • defaultEntities
  • entities
• Methods
  • encode
  • decode
• Entities

Construction

new EntityEncoder( [entities] )

Parameters

• entities Entities, EntityEncoder, or String (optional, default: "default")

  The set of entities (as either an entities object or a previously created EntityEncoder instance) that this EntityEncoder instance will use to encode and decode entities. This can also be the String value "default" which will cause this EntityEncoder instance to use the current set of default entities.

Properties

• defaultEntities Entities, EntityEncoder, or Null (static, write-only)

  The set of entities that new EntityEncoder instances will use when they are set to use the default set of entities. Setting this to null will set the default entities back to the basic set of entities that it started as:

  • & — ampersand (&),
  • ' — apostrophe ('),
  • © — copyright (©),
  • > — greater than (>),
  • < — less than (<),
  •   — non-breaking space ( ), and
  • " — quotation mark (").

  Changing defaultEntities will have no effect on pre-existing EntityEncoder instances, unless you explicitly set their entities property to "default" afterwards.

• entities Entities, EntityEncoder, or String (write-only)

  The set of entities that this EntityEncoder instance will use to encode and decode entities. This can also be set to the String value "default" which will cause this EntityEncoder instance to use the current set of default entities.

Methods

entities.encode( string[, what] )

Encodes the specified string, based on the entities of this EntityEncoder instance, turning characters into entity references (eg. "&" into "&").

Parameters

• string String

  The string to be encoded.

• what RegExp (optional)

  A regular expression that, if specified, is used to select the characters that will be encoded. If text is selected that doesn't have an entity associated with it, no encoding will be done on the selected text.

Return Value

The String that has been encoded.

---

entities.decode( string )

Decodes the specified string, based on the entities of this EntityEncoder instance, turning entity references into characters (eg. "&" into "&").

Parameters

• string String

  The string to be decoded.

Return Value

The String that has been decoded.

---

Entities

Which entities can be encoded and decoded can be customized with an object that consists of entity names as the object's keys and entity characters as the corresponding values. The entity characters can be specified either directly as a String (optionally with multiple characters), or as a numeric code point.

For instance, using the object:

{
    "Space": 32,
    "Jay": "J",
    "bns": "beans"
}

would encode "Jumping jellybeans" as "&Jay;umping&Space;jelly&bns;", and decode "&Jay;ack's&Space;&bns;talk" as "Jack's beanstalk".

This format was chosen specifically to be 100% compatible with the JSON data file "entities.json" in the popular NPM module entities by Felix Böhm in case your project already happens to include it. If you have access to this file (found in lib/maps inside entities' directory, as of version 2.0.0), you can JSON.parse() the contents of the file, using the result as the entities for FauxDOM's EntityEncoder.

If your project doesn't include Felix's entities module, FauxDOM has its own set of this same data, automatically downloaded from the WHATWG's HTML spec and processed to be as small as possible by the entities.js script.