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 😉.

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 😄.

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:

1. [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)
2. [String] url - The base-URL that got passed to emojiParser.parse-function.
3. [String] classes - The classes the img-tag should use.
4. [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]:" />

Installation

node.js

npm install emoji-parser

bower

bower install emoji-parser