Skip to content

Latest commit

 

History

History
325 lines (214 loc) · 8.74 KB

README.md

File metadata and controls

325 lines (214 loc) · 8.74 KB
Raw

Twemoji

Gem Version Build Status Inline docs

Twitter opensourced Twitter Emoji and the official JavaScript implementation is available at twemoji.

This RubyGem twemoji is a minimum implementation of Twitter Emoji in Ruby so that you can use emoji in your Ruby/Rails apps too!

Note: This gem might not implement all the features available in the JavaScript implementation.

Twemoji Gem and twemoji.js versions

  • Twemoji Gem 3.x supports twemoji.js V2 (1661 emojis) Preview
  • Twemoji Gem 2.x supports twemoji.js V1 (874 emojis) Preview

Preview pages' Images is CC-BY 4.0 by Twitter/Twemoji.

Installation

Add this line to your application's Gemfile:

gem "twemoji"

And then execute:

$ bundle

Or install it yourself as:

$ gem install twemoji

Integration

Twemoji and Rails

Rails Helper

$ touch app/helpers/emoji_helper.rb

module EmojiHelper
  def emojify(content, **options)
    Twemoji.parse(h(content), options).html_safe if content.present?
  end
end

In your ERb view:

<%= emojify "I like chocolate :heart_eyes:!" %>

will render

I like chocolate <img class="emoji" draggable="false" title=":heart_eyes:" alt="😍" src="https://twemoji.maxcdn.com/2/72x72/1f60d.png">!

More options could be passed in, please see Twemoji.parse options for more details.

Usage

API

Twemoji.find_by text or code or unicode

> Twemoji.find_by(text: ":heart_eyes:")
=> "1f60d"

> Twemoji.find_by(code: "1f60d")
=> ":heart_eyes:"

> Twemoji.find_by(unicode: "😍")
=> ":heart_eyes:"

> Twemoji.find_by(unicode: "\u{1f60d}")
=> ":heart_eyes:"

Twemoji.find_by_text

> Twemoji.find_by_text(":heart_eyes:")
=> "1f60d"

Twemoji.find_by_code

> Twemoji.find_by_code("1f60d")
=> ":heart_eyes:"

Twemoji.find_by_unicode

> Twemoji.find_by(unicode: "😍")
=> ":heart_eyes:"

Twemoji.render_unicode

> Twemoji.render_unicode ":heart_eyes:"
=> "😍"

> Twemoji.render_unicode "1f60d"
=> "😍"

Twemoji.parse

Parses for both name tokens (e.g. 😍) or unicode values (e.g. \u1f60d).

Parsing by name token:

> Twemoji.parse "I like chocolate :heart_eyes:!"
=> 'I like chocolate <img draggable="false" title=":heart_eyes:" alt="😍" src="https://twemoji.maxcdn.com/2/svg/1f60d.svg" class="emoji">!'

Parsing by name unicode values:

> Twemoji.parse "I like chocolate 😍!"
=> 'I like chocolate <img draggable="false" title=":heart_eyes:" alt="😍" src="https://twemoji.maxcdn.com/2/svg/1f60d.svg" class="emoji">!'

Parsing by both name and unicode:

> Twemoji.parse ":cookie: 🎂"
=> '<img draggable="false" title=":cookie:" alt="🍪" src="https://twemoji.maxcdn.com/2/svg/1f36a.svg" class="emoji"> <img draggable="false" title=":birthday:" alt="🎂" src="https://twemoji.maxcdn.com/2/svg/1f382.svg" class="emoji">'
Twemoji.parse options
asset_root

Default assets root url. Defaults to https://twemoji.maxcdn.com/2/:

> Twemoji.parse "I like chocolate :heart_eyes:!", asset_root: "foocdn.com"
=> 'I like chocolate <img draggable="false" title=":heart_eyes:" alt="😍" src="foocdn.com/svg/1f60d.svg" class="emoji">!'
file_ext

Default assets file extensions. Defaults to svg.

Can change to "png":

> Twemoji.parse 'I like chocolate :heart_eyes:!', file_ext: "png"
=> 'I like chocolate <img draggable="false" title=":heart_eyes:" alt="😍" src="https://twemoji.maxcdn.com/2/72x72/1f60d.png" class="emoji">!'
class_name

Default image CSS class name. Defaults to "emoji".

> Twemoji.parse "I like chocolate :heart_eyes:!", class_name: "superemoji"
=> 'I like chocolate <img draggable="false" title=":heart_eyes:" alt="😍" src="https://twemoji.maxcdn.com/2/svg/1f60d.svg" class="superemoji">!'
img_attrs

List of image attributes for the img tag. Optional.

> Twemoji.parse "I like chocolate :heart_eyes:!", class_name: "twemoji", img_attrs: { style: "height: 1.3em;" }
=> 'I like chocolate <img draggable="false" title=":heart_eyes:" alt="😍" src="https://twemoji.maxcdn.com/2/svg/1f60d.svg" class="twemoji" style="height: 1.3em;">!'

attribute value can apply proc-like object, remove : from title attribute:

> no_colons = ->(name) { name.gsub(":", "") }

> Twemoji.parse "I like chocolate :heart_eyes:!", class_name: "twemoji", img_attrs: { title: no_colons }
=> 'I like chocolate <img draggable="false" title="heart_eyes" alt="😍" src="https://twemoji.maxcdn.com/2/svg/1f60d.svg" class="twemoji">!'

Twemoji.emoji_pattern

> Twemoji.emoji_pattern
=> /(:mahjong:|:black_joker:| ... |:registered_sign:|:shibuya:)/

Twemoji.emoji_pattern_unicode

> Twemoji.emoji_pattern_unicode

Twemoji.emoji_pattern_all = emoji_pattern + emoji_pattern_unicode

> Twemoji.emoji_pattern_all

JSON for your front-end

We prepare two constants: Twemoji.png and Twemoji.svg (not loaded by default), you need to require them to use:

require "twemoji/png" # If you want to use Twemoji.png
require "twemoji/svg" # If you want to use Twemoji.svg

Or require at Gemfile:

# Require the one you need, require Twemoji::PNG
gem "twemoji", require: "twemoji/png"

# Or Twemoji::SVG
gem "twemoji", require: "twemoji/svg"

# Or both
gem "twemoji", require: ["twemoji/png", "twemoji/svg"]

Then you can do to_json to feed your front-end.

You can also make custom format by leverage Twemoji.codes:

# emojis.json.erb
<%= Twemoji.codes.collect do |code, _|
  Hash(
    value: code,
    html: content_tag(:span, Twemoji.parse(code).html_safe + " #{code}" )
  )
end.to_json.html_safe %>

Configuration

Twemoji.parse options can be given in configure block, default values are:

Twemoji.configure do |config|
  config.asset_root = "https://twemoji.maxcdn.com/2"
  config.file_ext   = "svg"
  config.class_name = "emoji"
  config.img_attrs  = {}
end

Specify additional img attributes like so:

config.img_attrs  = { style: "height: 1.3em;" }

Tips (from twitter/twemoji)

Inline Styles

If you'd like to size the emoji according to the surrounding text, you can add the following CSS to your stylesheet:

img.emoji {
  height: 1em;
  width: 1em;
  margin: 0 .05em 0 .1em;
  vertical-align: -0.1em;
}

This will make sure emoji derive their width and height from the font-size of the text they're shown with. It also adds just a little bit of space before and after each emoji, and pulls them upwards a little bit for better optical alignment.

UTF-8 Character Set

To properly support emoji, the document character must be set to UTF-8. This can done by including the following meta tag in the document 

<meta charset="utf-8">

Attribution Requirements

IMPORTANT: Please follow the Attribution Requirements as stated on the official Twemoji (JavaScript) repo.

Contributing

Please see the CONTRIBUTING.md file.

Credits

A huge THANK YOU to all our contributors! ❤️

The emoji keywords are from jollygoodcode/emoji-keywords.

Guidelines

This project subscribes to the Moya Contributors Guidelines which TLDR: means we give out push access easily and often.

License

Please see the LICENSE.md file.

Maintained by Jolly Good Code

Jolly Good Code

We specialise in rapid development of high quality MVPs. Hire us to turn your product idea into reality.