A gem for EmojiOne
Clone or download
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
assets
config
lib Bumping version to v3.3.0 Jul 14, 2017
test
.gitignore
.ruby-version
.travis.yml
CHANGELOG.md
Gemfile
LICENSE.txt
README.md
Rakefile
gemojione.gemspec

README.md

Gemojione

Build Status Downloads Version Dependencies Coverage GPA

A gem for EmojiOne

This gem exposes the emojione unicode/image assets and APIs for working with them.

Easily lookup emoji name, unicode character, or image assets and convert emoji representations.

Maintainer Notice

This project is not currently maintained, I'm afraid I don't have the time nor the Ruby expertise to carry this project forward anymore. If by any chance someone wants to push this project forward feel free to contact me to discuss it.

Installation

Add this line to your application's Gemfile:

gem 'gemojione'

And then execute:

$ bundle

Or install it yourself as:

$ gem install gemojione

Install emoji image library assets:

$ rake gemojione:install_assets
====================================================================
= emoji image assets install
= Target: /Users/user/src/rails-app/app/assets/images/emoji
= Source: /Users/user/src/emoji/assets
====================================================================
- Creating /Users/user/src/rails-app/app/assets/images/emoji...
- Installing assets...

Usage

You can use this gem to replace unicode emoji characters with img tags linking to the appropriate emoji image.

Image Replacement APIs:

> Gemojione.replace_unicode_moji_with_images('I ❤ Emoji')
=> "I <img alt=\"\" class=\"emoji\" src=\"http://localhost:3000/assets/emoji/2764.png\"> Emoji"

> Gemojione.replace_named_moji_with_images('I :heart: Emoji')
=> "I <img alt=\"\" class=\"emoji\" src=\"http://localhost:3000/assets/emoji/2764.png\"> Emoji"

> Gemojione.image_url_for_unicode_moji('')
=> "http://localhost:3000/assets/emoji/2764.png"

> Gemojione.image_url_for_name('heart')
=> "http://localhost:3000/assets/emoji/2764.png"

> Gemojione.replace_ascii_moji_with_images("I <3 Emoji")
=> "I <img alt=\"\" class=\"emoji\" src=\"http://localhost:3000/assets/emoji/2764.png\"> Emoji"

Sprite Replacement APIs:

Gemojione.use_sprite=true
> Gemojione.replace_unicode_moji_with_images("I ❤ Emoji")
=> "I <span class=\"emojione emojione-2764\" alt=\"\" title=\"\">❤</span> Emoji"

> Gemojione.replace_named_moji_with_images("I :heart: Emoji")
=> "I <span class=\"emojione emojione-2764\" alt=\"\" title=\"\">❤</span> Emoji"

> Gemojione.replace_ascii_moji_with_images("I <3 Emoji")
=> "I <span class=\"emojione emojione-2764\" alt=\"\" title=\"\">❤</span> Emoji"

Emoji Library Index APIs:

> index = Gemojione::Index.new

> index.find_by_name('heart')

=> {"moji"=>"", "unicode"=>"2764", "unicode_alternates"=>["2764-FE0F"], "name"=>"heart", "shortname"=>":heart:", "category"=>"symbols", "aliases"=>[], "aliases_ascii"=>["<3"], "keywords"=>["like", "love", "red", "pink", "black", "heart", "love", "passion", "romance", "intense", "desire", "death", "evil", "cold", "valentines"], "description"=>"heavy black heart"}

> index.find_by_moji('')
=> {"moji"=>"", "unicode"=>"2764", "unicode_alternates"=>["2764-FE0F"], "name"=>"heart", "shortname"=>":heart:", "category"=>"symbols", "aliases"=>[], "aliases_ascii"=>["<3"], "keywords"=>["like", "love", "red", "pink", "black", "heart", "love", "passion", "romance", "intense", "desire", "death", "evil", "cold", "valentines"], "description"=>"heavy black heart"}

> index.find_by_keyword('teeth')
=> [{"unicode"=>"1F62C", "unicode_alternates"=>[], "name"=>"grimacing", "shortname"=>":grimacing:", "category"=>"people", "aliases"=>[], "aliases_ascii"=>[], "keywords"=>["face", "grimace", "teeth", "disapprove", "pain", "silly", "smiley", "emotion", "selfie"], "moji"=>"😬", "description"=>"grimacing face"}, {"unicode"=>"1F479", "unicode_alternates"=>[], "name"=>"japanese_ogre", "shortname"=>":japanese_ogre:", "category"=>"people", "aliases"=>[], "aliases_ascii"=>[], "keywords"=>["monster", "japanese", "oni", "demon", "troll", "ogre", "folklore", "devil", "mask", "theater", "horns", "teeth"], "moji"=>"👹", "description"=>"japanese ogre"}]

> index.find_by_ascii(':)')
=> {"unicode"=>"1F604", "unicode_alternates"=>[], "name"=>"smile", "shortname"=>":smile:", "category"=>"people", "aliases"=>[], "aliases_ascii"=>[":)", ":-)", "=]", "=)", ":]"], "keywords"=>["face", "funny", "haha", "happy", "joy", "laugh", "smile", "smiley", "smiling", "emotion"], "moji"=>"😄","description"=>"smiling face with open mouth and smiling eyes"}

Default configuration integrates with Rails, but you can change it with an initializer:

# config/initializers/gemojione.rb
Gemojione.asset_host = "emoji.cdn.com"
Gemojione.asset_path = '/assets/emoji'
Gemojione.default_size = '64px'
Gemojione.use_svg = true
Gemojione.use_sprite = true

You can also serve the assets directly from the gem in your rails app:

# config/application.rb
config.assets.paths << Gemojione.images_path
config.assets.precompile << "emoji/*.png" 
# or 
config.assets.precompile << "emoji/*.svg"

#for spritesheets
config.assets.paths << Gemojione.sprites_path
config.assets.precompile << "emojione.sprites.css"
config.assets.precompile << "emojione.sprites.png"

String Helper Methods:

You can also

include 'gemojione/string_ext'

and call methods directly on your string to return the same results:

> 'I ❤ Emoji'.with_emoji_images
=> "I <img alt=\"\" class=\"emoji\" src=\"http://localhost:3000/assets/emoji/2764.png\"> Emoji"

> 'I :heart: Emoji'.with_emoji_names
=> "I <img alt=\"\" class=\"emoji\" src=\"http://localhost:3000/assets/emoji/2764.png\"> Emoji"

> 'heart'.image_url
> ''.image_url
=> "http://localhost:3000/assets/emoji/2764.png"

> 'heart'.emoji_data
> ''.emoji_data
=> {"moji"=>"", "unicode"=>"2764", "unicode_alternates"=>["2764-FE0F"], "name"=>"heart", "shortname"=>":heart:", "category"=>"symbols", "aliases"=>[], "aliases_ascii"=>["<3"], "keywords"=>["like", "love", "red", "pink", "black", "heart", "love", "passion", "romance", "intense", "desire", "death", "evil", "cold", "valentines"], "description"=>"heavy black heart"}

HTML Safety and Performance

This gem uses pure ruby code for compatibility with different Ruby virtual machines. However, there can be significant performance gains to escaping incoming HTML strings using optimized, native code in the escape_utils gem.

The emoji gem will try to use escape_utils if it's available, but does not require it. Benchmarks show a 10x-100x improvement in HTML escaping performance, based on the size of the string being processed.

To enable native HTML escaping, add this line to your application's Gemfile:

gem 'escape_utils'

Spritesheet scaling

If you’re using spritesheets, customising Gemojione.default_size at config/initializers/gemojione.rb won’t work. Default size for sprite tag is 64px x 64px, but zoom or transform: scale() can be used for custom scaling. transform: scale() is more widely supported.

.emojione{
  transform: scale(.5);
  margin: -15px;
}

Projects using the gem

If your application uses the gem, open a PR and show your project's ❤️ for the gem so it gets listed here.

Contributors: ❤️

This gem is a former fork of the emoji gem that has been adapted for EmojiOne.

Contributing

  1. Fork it
  2. Bundle Install (bundle install)
  3. Run the Tests (rake test)
  4. Create your feature branch (git checkout -b my-new-feature)
  5. Commit your changes (git commit -am 'Add some feature')
  6. Push to the branch (git push origin my-new-feature)
  7. Create new Pull Request

Notes

Run rake resprite to regenerate the spritesheets if you're adding new images