Emoji-parser NPM

emoji-parser for node.js and bower

About

Server-Side (node.js)

This script makes it easy to keep the emoji-images in sync with the official repository of emoji-cheat-sheet.com. It's just an additional call on server-startup (or whenever you want to synchronize).

The actual parsing works without any DOM-manipulation or whatever, just a simple replace call.

Client-Side (bower)

The actual bower-component is located within the emoji-parser-bower repository, but it gets generated by grunt using only files within this repository.

On client-side you may use this script to easily parse the emoji (like server-side) without any DOM-manipulation.

When used client-side this module of cause cannot ensure that you're using the latest emoji images but I'll try to keep it up-to-date :wink:.

Why another one?

This project is inspired by emoji-images, but this project hasn't been modified for some time now and the author isn't responding to issues.

Because of this and a few more customizations I rewrote this in coffee-script which is much more fun to code :smile:.

So this has become way more customizable (up to passing own parser-function) and the emoji-synchronization happens server-side instead of project-side.

Usage

API

node.js (server-side)

var emojiParser = require('emoji-parser');

emojiParser.init([directory]) initializes the module.
- directory (default: module-path + '/emoji') - The file-system path of the directory where to store the images (without trailing /).
emojiParser.update([remain], [token], [callback]) downloads missing emoji images to keep your images up-to-date.
- remain (default: true) - If false the directory gets cleared before downloading all images. Otherwise only images get loaded that don't already exist.
- token (default: null) - If set it will get used as GitHub access_token.
- callback (default: null) - Function that gets called after update is complete.
[String] emojiParser.parse(text, url, [options]) replaces all emoji-occurrences within given text.
- text - The text to parse.
- url - The base-url where the clients find the images (without trailing /).
- options (default: {}) - The options to use for parsing:
  - list: A list of emoji to overwrite default one.
  - parser: A Parser (see below) to replace the default parser.
  - classes: A String of the content for the class-attribute of the img-tag (default parser).
  - attributes (default: {'title':function(match,name,parameter){if (parameter != null) return parameter + " (" + name + ")"; else return name;}, 'alt':function(match){return match;}}): An object of attributes and their value-producing function (gets passed matching string, emoji-name and parameter (if any): ":smiley[parameter]:", "smiley", "parameter"). The attributes get added to the img-tag with the generated values (default parser).
- Returns the text with parsed emoji.
[String] emojiParser.parse(text, url, parser) replaces all emoji-occurrences within given text, using given parser.
- text - The text to parse.
- url - The base-URL to pass to the parser (without trailing /).
- parser - The Parser (see below) to use.
- Returns the text with parsed emoji.
[Array of Strings] emojiParser.list([newList]) - Getter and/or Setter for the list of available images.
- newList (default: null) - The list to use for parsing, gets ignored if null.
- Returns the list of emoji that get used for parsing (not sorted).
[Array of Strings] emojiParser.emoji - The list of images that have been found on file-system or got downloaded by emojiParser.update(...).

bower (client-side)

If you use require.js or similar frameworks you can use it to get the module, otherwise you can use window.emojiParser.

[String] emojiParser(text, url, [options]) replaces all emoji-occurrences within given text.
- text - The text to parse.
- url - The base-url where the clients find the images (without trailing /).
- options (default: {}) - The options to use for parsing:
  - list: A list of emoji to overwrite default one.
  - parser: A Parser (see below) to replace the default parser.
  - classes: A String of the content for the class-attribute of the img-tag (default parser).
  - attributes (default: {'title':function(match,name,parameter){if (parameter != null) return parameter + " (" + name + ")"; else return name;}, 'alt':function(match){return match;}}): An object of attributes and their value-producing function (gets passed matching string, emoji-name and parameter (if any): ":smiley[parameter]:", "smiley", "parameter"). The attributes get added to the img-tag with the generated values (default parser).
[String] emojiParser(text, url, parser) replaces all emoji-occurrences within given text, using given parser.
- text - The text to parse.
- url - The base-URL to pass to the parser (without trailing /).
- parser - The Parser (see below) to use.
- Returns the text with parsed emoji.
[Array of Strings] emojiParser.list([newList]) - Getter and/or Setter for the list of available images.
- newList (default: null) - The list to use for parsing, gets ignored if null.
- Returns the list of emoji that get used for parsing (not sorted).

Parser

A parser is just a function that gets called for each emoji-occurrence with the following parameters:

[Array] match - An array containing the string that gets interpreted as emoji, the name of the emoji and the parameter for the emoji (if any)
[String] url - The base-URL that got passed to emojiParser.parse-function.
[String] classes - The classes the img-tag should use.
[Object] options - The options that get used by the emojiParser.parse-function.

The return-value will replace the emoji-occurrence.

Example

node.js

var emoji = require('emoji-parser');

// keep emoji-images in sync with the official repository
emoji.init().update();

// calls to http://example.com/emoji/images/*.png should resolve to path/to/node_modules/emoji-parser/emoji/*.png
emoji.parse('This is a :telephone: :smiley[:D]:', 'http://example.com/emoji/images');
// This is a <img class="emoji" src="http://example.com/emoji/images/telephone.png" title="telephone" alt=":telephone:" /> <img class="emoji" src="http://example.com/emoji/images/smiley.png" title=":D (smiley)" alt=":smiley[:D]:" />

bower

var emoji = require ? require('emoji-parser') : window.emojiParser;

emoji('This is a :telephone: :smiley[:D]:', 'http://example.com/emoji/images');
// This is a <img class="emoji" src="http://example.com/emoji/images/telephone.png" title="telephone" alt=":telephone:" /> <img class="emoji" src="http://example.com/emoji/images/smiley.png" title=":D (smiley)" alt=":smiley[:D]:" />