Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/fenwick67/neato-emoji-converter
Convert unicode emoji, shortcodes and custom emoji
https://github.com/fenwick67/neato-emoji-converter
Last synced: about 1 month ago
JSON representation
Convert unicode emoji, shortcodes and custom emoji
- Host: GitHub
- URL: https://github.com/fenwick67/neato-emoji-converter
- Owner: fenwick67
- License: mit
- Created: 2019-09-05T23:37:02.000Z (over 5 years ago)
- Default Branch: master
- Last Pushed: 2019-10-10T00:18:33.000Z (about 5 years ago)
- Last Synced: 2024-10-28T01:05:48.251Z (about 2 months ago)
- Language: JavaScript
- Size: 12.7 KB
- Stars: 2
- Watchers: 2
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Neato-emoji-converter
Convert to and from actual emoji (💖), short codes (`:pizza:`), and to arbitrary formats. Supports custom emoji for any unicode sequence and/or shortcode.
# Documentation
This package exposes one class, Converter.
## `new EmojiConverter([sources = [ Converter.EMOJI_DEFAULT_SOURCE] ])`
Returns a converter instance. The default constructor initializes it with the official Unicode emojis. You can specify different sources.
A source should be an array of objects, each object representing an emoji. Each should have at least a `shortname` (needs to be surrounded with colons), optionally a `name`, optionally a `unicode` (the actual unicode character), and optionally a `shortname_alternates` (an array of alternate shortnames, each surrouned with colons). You can also provide any other options you want to these objects and they will be available to a custom replacer. Sources are applied from left to right (rightmost source has most priority).
## The Converter Instance
### `converterInstance.replaceUnicode(str)`
Replace unicode emoji in a string with `:shortcode:`s.
### `converterInstance.replaceShortcodes(str)`
replace `:shortcode:`s with unicode emojis in a string
### `converterInstance.replaceShortcodesWith(str, replacer)`
Every `:shortcode:` emoji that you have defined in your sources will be replaced with the function you specify.
The function is called with `(unicodeCharacter, shortcode, emojiName, emojiObject)`. `emojiObject` is the original emoji object from the source provided in the constructor.
### `converterInstance.replaceUnicodeWith(str, replacer)`
Same as `replaceShortcodesWith`, but operates only on unicode emojis that are recognized..
### `converterInstance.replaceWith(str, replacer)`
Same as `replaceShortcodesWith`, but operates on short code and unicode emojis that are recognized.
### `converterInstance.normalizeShortcodes(str)`
Sometimes emojis have multiple names (such as `:celtic_cross:` vs `:cross:`). This will ensure the canonical one is used.
## Converter Prototype
### `Converter.EMOJI_DEFAULT_SOURCE`
This is the default source of emojis, it allows the converter to find all official unicode emoji.
### `Converter.unicodeToPointsString(unicodeStr)`
converts, for example, `'🙆🏿♂️'` to `'1f646-1f3ff-200d-2642-fe0f'`
# Examples
## Shortcodes to Unicode
```js
converter.replaceShortcodes('I:heart:NY')
// => 'I❤️NY'
```
## Unicode to shortcodes
```js
converter.replaceUnicode("❤️~~🐧~~❤️")
// => ":heart:~~:penguin:~~:heart:"
```
## Custom HTML rendering of official Emoji
```js
var str = ':heart: its me, 🦃!'
function renderEmojiHowIWant(unicodeChar, shortcode, name){
var codepointString = Converter.unicodeToPointsString(unicodeChar)
return `
`
}
var htmlified = converter.replaceUnicodeWith(str,renderEmojiHowIWant)
// => '
its me, 
!'
```
## Advanced: add custom Emoji as `![]()
` tags, convert other shortcodes to unicode
```js
var emojiData = [
{ shortname: ':charizard:', url: "http://somewhere.com/charizard.png" }
]
var converter = new EmojiConverter([Converter.EMOJI_DEFAULT_SOURCE, emojiData])
var chatText = ':charizard: ❤️ :pancakes: :wow:'
var pokemanned = converter.replaceShortcodesWith(chatText, function(unicodeChar, shortcode, name, object){
if (unicodeChar){return unicodeChar}
else if (object.url){return `
`}
else{ return shortcode }
})
// =>'
❤️ 🥞 :wow:'
```
## Advanced: plain-text replacement
```js
var replacements = [
{ shortname: ":heart:", unicode: '❤', terminalReplacement: '<3'},
{ shortname: ":heart:", unicode: '❤️', terminalReplacement: '<3'},
{ shortname: ":blush:", unicode: '😊', terminalReplacement: '^__^'},
{ shortname: ":simple_smile:", unicode: '🙂', terminalReplacement: ':)'},
{ shortname: ":smiley:", unicode: '😃', terminalReplacement: ':D'},
{shortname: ':laughing:', unicode: '😆', terminalReplacement: 'XD'}
]
var converter = new Converter([Converter.EMOJI_DEFAULT_SOURCE, replacements])
var chatText = 'I ❤ ❤️ Unicode 🙂, but I also :heart: short codes 😊! (and 🍬 😆)'
converter.replaceWith(chatText, function(unicodeChar, shortcode, name, object){
return object.terminalReplacement || shortcode || unicodeChar
})
// => 'I <3 <3 Unicode :), but I also <3 short codes ^__^! (and :candy: XD)'
```