api documentation for emojione (v2.2.7)

Emoji One is a complete set of emojis designed for the web. It includes libraries to easily convert unicode characters to shortnames (:smile:) and shortnames to our custom emoji images. PNG and SVG formats provided for the emoji images.

module emojione
1. boolean emojione.ascii
2. boolean emojione.imageTitleTag
3. boolean emojione.sprites
4. boolean emojione.unicodeAlt
5. function emojione.convert (unicode)
6. function emojione.escapeHTML (string)
7. function emojione.escapeRegExp (string)
8. function emojione.getUnicodeReplacementRegEx ()
9. function emojione.mapEmojioneList (addToMapStorage)
10. function emojione.mapUnicodeCharactersToShort ()
11. function emojione.mapUnicodeToShort ()
12. function emojione.memoizeReplacement ()
13. function emojione.objectFlip (obj)
14. function emojione.replaceAll (string, find, replacementList)
15. function emojione.shortnameToAscii (str)
16. function emojione.shortnameToImage (str)
17. function emojione.shortnameToUnicode (str)
18. function emojione.toImage (str)
19. function emojione.toShort (str)
20. function emojione.unescapeHTML (string)
21. function emojione.unicodeToImage (str)
22. function emojione.unifyUnicode (str)
23. object emojione.asciiList
24. object emojione.emojioneList
25. object emojione.jsEscapeMap
26. object emojione.regAscii
27. object emojione.regShortNames
28. object emojione.regUnicode
29. string emojione.asciiRegexp
30. string emojione.cacheBustParam
31. string emojione.imagePathPNG
32. string emojione.imagePathSVG
33. string emojione.imagePathSVGSprites
34. string emojione.imageType
35. string emojione.shortnames
36. string emojione.unicodeRegexp

module emojione

function emojione.convert (unicode)

description and source-code

convert = function (unicode) {
    if(unicode.indexOf("-") > -1) {
        var parts = [];
        var s = unicode.split('-');
        for(var i = 0; i < s.length; i++) {
            var part = parseInt(s[i], 16);
            if (part >= 0x10000 && part <= 0x10FFFF) {
                var hi = Math.floor((part - 0x10000) / 0x400) + 0xD800;
                var lo = ((part - 0x10000) % 0x400) + 0xDC00;
                part = (String.fromCharCode(hi) + String.fromCharCode(lo));
            }
            else {
                part = String.fromCharCode(part);
            }
            parts.push(part);
        }
        return parts.join('');
    }
    else {
        var s = parseInt(unicode, 16);
        if (s >= 0x10000 && s <= 0x10FFFF) {
            var hi = Math.floor((s - 0x10000) / 0x400) + 0xD800;
            var lo = ((s - 0x10000) % 0x400) + 0xDC00;
            return (String.fromCharCode(hi) + String.fromCharCode(lo));
        }
        else {
            return String.fromCharCode(s);
        }
    }
}

example usage
```
n/a
```

function emojione.escapeHTML (string)

description and source-code

escapeHTML = function (string) {
    var escaped = {
        '&' : '&amp;',
        '<' : '&lt;',
        '>' : '&gt;',
        '"' : '&quot;',
        '\'': '&#039;'
    };

    return string.replace(/[&<>"']/g, function (match) {
        return escaped[match];
    });
}

example usage
```
n/a
```

function emojione.escapeRegExp (string)

description and source-code

escapeRegExp = function (string) {
    return string.replace(/[-[\]{}()*+?.,;:&\\^$#\s]/g, "\\$&");
}

example usage
```
n/a
```

function emojione.getUnicodeReplacementRegEx ()

description and source-code

getUnicodeReplacementRegEx = function () {
    ns.memoizeReplacement();
    return ns.unicodeReplacementRegEx;
}

example usage
```
n/a
```

function emojione.mapEmojioneList (addToMapStorage)

description and source-code

mapEmojioneList = function (addToMapStorage) {
    for (var shortname in ns.emojioneList) {
        if (!ns.emojioneList.hasOwnProperty(shortname)) { continue; }
        for (var i = 0, len = ns.emojioneList[shortname].unicode.length; i < len; i++) {
            var unicode = ns.emojioneList[shortname].unicode[i];
            addToMapStorage(unicode, shortname);
        }
    }
}

example usage
```
n/a
```

function emojione.mapUnicodeCharactersToShort ()

description and source-code

mapUnicodeCharactersToShort = function () {
    ns.memoizeReplacement();
    return ns.memMapShortToUnicodeCharacters;
}

example usage
```
n/a
```

function emojione.mapUnicodeToShort ()

description and source-code

mapUnicodeToShort = function () {
    if (!ns.memMapShortToUnicode) {
        ns.memMapShortToUnicode = {};
        ns.mapEmojioneList(function (unicode, shortname) {
            ns.memMapShortToUnicode[unicode] = shortname;
        });
    }
    return ns.memMapShortToUnicode;
}

example usage
```
n/a
```

function emojione.memoizeReplacement ()

description and source-code

memoizeReplacement = function () {
    if (!ns.unicodeReplacementRegEx || !ns.memMapShortToUnicodeCharacters) {
        var unicodeList = [];
        ns.memMapShortToUnicodeCharacters = {};
        ns.mapEmojioneList(function (unicode, shortname) {
            var emojiCharacter = ns.convert(unicode);
            if(ns.emojioneList[shortname].isCanonical) {
                ns.memMapShortToUnicodeCharacters[emojiCharacter] = shortname;
            }
            unicodeList.push(emojiCharacter);
        });
        ns.unicodeReplacementRegEx = unicodeList.join('|');
    }
}

example usage
```
n/a
```

function emojione.objectFlip (obj)

description and source-code

objectFlip = function (obj) {
    var key, tmp_obj = {};

    for (key in obj) {
        if (obj.hasOwnProperty(key)) {
            tmp_obj[obj[key]] = key;
        }
    }

    return tmp_obj;
}

example usage
```
n/a
```

function emojione.replaceAll (string, find, replacementList)

description and source-code

replaceAll = function (string, find, replacementList) {
    var escapedFind = ns.escapeRegExp(find);
    var search = new RegExp("<object[^>]*>.*?<\/object>|<span[^>]*>.*?<\/span>|<(?:object|embed|svg|img|div|span|p|a)[^>]*>|("+escapedFind
+")", "gi");

    // callback prevents replacing anything inside of these common html tags as well as between an <object></object> tag
    var replace = function(entire, m1) {
        return ((typeof m1 === 'undefined') || (m1 === '')) ? entire : replacementList[m1];
    };

    return string.replace(search,replace);
}

example usage
```
n/a
```

function emojione.shortnameToAscii (str)

description and source-code

shortnameToAscii = function (str) {
    var unicode,
    // something to keep in mind here is that array flip will destroy
    // half of the ascii text "emojis" because the unicode numbers are duplicated
    // this is ok for what it's being used for
        unicodeToAscii = ns.objectFlip(ns.asciiList);

    str = str.replace(ns.regShortNames, function(shortname) {
        if( (typeof shortname === 'undefined') || (shortname === '') || (!(shortname in ns.emojioneList)) ) {
            // if the shortname doesnt exist just return the entire match
            return shortname;
        }
        else {
            unicode = ns.emojioneList[shortname].unicode[ns.emojioneList[shortname].unicode.length-1];
            if(typeof unicodeToAscii[unicode] !== 'undefined') {
                return unicodeToAscii[unicode];
            } else {
                return shortname;
            }
        }
    });
    return str;
}

example usage
```
n/a
```

function emojione.shortnameToImage (str)

description and source-code

shortnameToImage = function (str) {
    // replace regular shortnames first
    var replaceWith,unicode,alt,title;
    str = str.replace(ns.regShortNames, function(shortname) {
        if( (typeof shortname === 'undefined') || (shortname === '') || (!(shortname in ns.emojioneList)) ) {
            // if the shortname doesnt exist just return the entire match
            return shortname;
        }
        else {
            unicode = ns.emojioneList[shortname].unicode[ns.emojioneList[shortname].unicode.length-1];
            title = ns.imageTitleTag ? 'title="'+shortname+'"' : '';

            // depending on the settings, we'll either add the native unicode as the alt tag, otherwise the shortname
            alt = (ns.unicodeAlt) ? ns.convert(unicode.toUpperCase()) : shortname;

            if(ns.imageType === 'png') {
                if(ns.sprites) {
                    replaceWith = '<span class="emojione emojione-'+unicode+'" ' + title + '>'+alt+'</span>';
                }
                else {
                    replaceWith = '<img class="emojione" alt="'+alt+'" ' + title + ' src="'+ns.imagePathPNG+unicode+'.png'+ns.cacheBustParam
+'"/>';
                }
            }
            else {
                // svg
                if(ns.sprites) {
                    replaceWith = '<svg class="emojione"><description>'+alt+'</description><use xlink:href="'+ns.imagePathSVGSprites
+'#emoji-'+unicode+'"></use></svg>';
                }
                else {
                    replaceWith = '<object class="emojione" data="'+ns.imagePathSVG+unicode+'.svg'+ns.cacheBustParam+'" type="image
/svg+xml" standby="'+alt+'">'+alt+'</object>';
                }
            }

            return replaceWith;
        }
    });

    // if ascii smileys are turned on, then we'll replace them!
    if (ns.ascii) {

        str = str.replace(ns.regAscii, function(entire, m1, m2, m3) {
            if( (typeof m3 === 'undefined') || (m3 === '') || (!(ns.unescapeHTML(m3) in ns.asciiList)) ) {
                // if the ascii doesnt exist just return the entire match
                return entire;
            }

            m3 = ns.unescapeHTML(m3);
            unicode = ns.asciiList[m3];
            title = ns.imageTitleTag ? 'title="'+ns.escapeHTML(m3)+'"' : '';

            // depending on the settings, we'll either add the native unicode as the alt tag, otherwise the shortname
            alt = (ns.unicodeAlt) ? ns.convert(unicode.toUpperCase()) : ns.escapeHTML(m3);

            if(ns.imageType === 'png') {
                if(ns.sprites) {
                    replaceWith = m2+'<span class="emojione emojione-'+unicode+'"  ' + title + '>'+alt+'</span>';
                }
                else {
                    replaceWith = m2+'<img class="emojione" alt="'+alt+'" ' + title + ' src="'+ns.imagePathPNG+unicode+'.png'+ns
.cacheBustParam+'"/>';
                }
            }
            else {
                // svg
                if(ns.sprites) {
                    replaceWith = '<svg class="emojione"><description>'+alt+'</description><use xlink:href="'+ns.imagePathSVGSprites
+'#emoji-'+unicode+'"></use></svg>';
                }
                else {
                    replaceWith = m2+'<object class="emojione" data="'+ns.imagePathSVG+unicode+'.svg'+ns.cacheBustParam+'" type="
image/svg+xml" standby="'+alt+'">'+alt+'</object>';
                }
            }

            return replaceWith;
        });
    }

    return str;
}

example usage
```
n/a
```

function emojione.shortnameToUnicode (str)

description and source-code

shortnameToUnicode = function (str) {
    // replace regular shortnames first
    var unicode,fname,uc;
    str = str.replace(ns.regShortNames, function(shortname) {
        if( (typeof shortname === 'undefined') || (shortname === '') || (!(shortname in ns.emojioneList)) ) {
            // if the shortname doesnt exist just return the entire match
            return shortname;
        }
        unicode = ns.emojioneList[shortname].unicode[0].toUpperCase();
        fname = ns.emojioneList[shortname].fname;
        uc = ns.emojioneList[shortname].uc;
        //return ns.convert(unicode);
        return ns.convert(uc);
    });

    // if ascii smileys are turned on, then we'll replace them!
    if (ns.ascii) {

        str = str.replace(ns.regAscii, function(entire, m1, m2, m3) {
            if( (typeof m3 === 'undefined') || (m3 === '') || (!(ns.unescapeHTML(m3) in ns.asciiList)) ) {
                // if the shortname doesnt exist just return the entire match
                return entire;
            }

            m3 = ns.unescapeHTML(m3);
            unicode = ns.asciiList[m3].toUpperCase();
            return m2+ns.convert(unicode);
        });
    }

    return str;
}

example usage
```
n/a
```

function emojione.toImage (str)

description and source-code

toImage = function (str) {
    str = ns.unicodeToImage(str);
    str = ns.shortnameToImage(str);
    return str;
}

example usage
```
n/a
```

function emojione.toShort (str)

description and source-code

toShort = function (str) {
    var find = ns.getUnicodeReplacementRegEx(),
        replacementList = ns.mapUnicodeCharactersToShort();
    return  ns.replaceAll(str, find,replacementList);
}

example usage
```
n/a
```

function emojione.unescapeHTML (string)

description and source-code

unescapeHTML = function (string) {
    var unescaped = {
        '&amp;'  : '&',
        '&#38;'  : '&',
        '&#x26;' : '&',
        '&lt;'   : '<',
        '&#60;'  : '<',
        '&#x3C;' : '<',
        '&gt;'   : '>',
        '&#62;'  : '>',
        '&#x3E;' : '>',
        '&quot;' : '"',
        '&#34;'  : '"',
        '&#x22;' : '"',
        '&apos;' : '\'',
        '&#39;'  : '\'',
        '&#x27;' : '\''
    };

    return string.replace(/&(?:amp|#38|#x26|lt|#60|#x3C|gt|#62|#x3E|apos|#39|#x27|quot|#34|#x22);/ig, function (match) {
        return unescaped[match];
    });
}

example usage
```
n/a
```

function emojione.unicodeToImage (str)

description and source-code

unicodeToImage = function (str) {

    var replaceWith,unicode,short,fname,alt,title;
    var mappedUnicode = ns.mapUnicodeToShort();
    str = str.replace(ns.regUnicode, function(unicodeChar) {
        if( (typeof unicodeChar === 'undefined') || (unicodeChar === '') || (!(unicodeChar in ns.jsEscapeMap)) ) {
            // if the unicodeChar doesnt exist just return the entire match
            return unicodeChar;
        }
        else {
            // get the unicode codepoint from the actual char
            unicode = ns.jsEscapeMap[unicodeChar];

            //then map to shortname and locate the filename
            short = mappedUnicode[unicode];
            fname = ns.emojioneList[short].fname;

            // depending on the settings, we'll either add the native unicode as the alt tag, otherwise the shortname
            alt = (ns.unicodeAlt) ? ns.convert(unicode.toUpperCase()) : short;
            title = ns.imageTitleTag ? 'title="'+short+'"' : '';

            if(ns.imageType === 'png') {
                if(ns.sprites) {
                    replaceWith = '<span class="emojione emojione-'+unicode+'" ' + title + '>'+alt+'</span>';
                }
                else {
                    replaceWith = '<img class="emojione" alt="'+alt+'" ' + title + ' src="'+ns.imagePathPNG+fname+'.png'+ns.cacheBustParam
+'"/>';
                }
            }
            else {
                // svg
                if(ns.sprites) {
                    replaceWith = '<svg class="emojione"><description>'+alt+'</description><use xlink:href="'+ns.imagePathSVGSprites
+'#emoji-'+unicode+'"></use></svg>';
                }
                else {
                    replaceWith = '<img class="emojione" alt="'+alt+'" ' + title + ' src="'+ns.imagePathSVG+fname+'.svg'+ns.cacheBustParam
+'"/>';
                }
            }

            return replaceWith;
        }
    });

    return str;
}

example usage
```
n/a
```

function emojione.unifyUnicode (str)

description and source-code

unifyUnicode = function (str) {
    str = ns.toShort(str);
    str = ns.shortnameToUnicode(str);
    return str;
}

example usage
```
n/a
```

[ this document was created with utility2 ]

api documentation for emojione (v2.2.7)

Emoji One is a complete set of emojis designed for the web. It includes libraries to easily convert unicode characters to shortnames (:smile:) and shortnames to our custom emoji images. PNG and SVG formats provided for the emoji images.

table of contents