File: README.md

package info (click to toggle)
libjs-emojify 1.1.0+dfsg-2
  • links: PTS, VCS
  • area: main
  • in suites: bullseye, buster, sid
  • size: 5,972 kB
  • sloc: makefile: 4
file content (178 lines) | stat: -rw-r--r-- 6,569 bytes parent folder | download
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
# emojify.js

[![npm version][ico-npm]][package-npm]
[![Bower version][ico-bower]][package-bower]
[![MIT Licensed][ico-license]][license]
[![Gitter chat][ico-gitter]][gitter]

---

Master | Develop
--- | ---
[![Master branch build status][ico-build]][travis] | [![Develop branch build status][ico-build-dev]][travis]
[![Master branch Windows build status][ico-windows-build]][appveyor] | [![Develop branch Windows build status][ico-windows-build-dev]][appveyor]

[![Browser Results](https://ci.testling.com/hassankhan/emojify.js.png)](https://ci.testling.com/hassankhan/emojify.js)

A swiss-army-knife for all emoji, in Javascript. Used by [Gitter](https://gitter.im/) and [Mapbox](https://www.mapbox.com/blog/emoji-map-markers/).

The emoji keywords are as described by [emoji-cheat-sheet.com](http://www.emoji-cheat-sheet.com).

Go to this project's [GitHub pages](http://hassankhan.github.com/emojify.js) to see the code in action.

## Features

- Fast
- Awesome
- Converts emoticons like `:) :( :'(`
- Allows customisation of processed emoji
- Multiple modes; `img`, sprites and data-URI
- Available on a CDN **(gasp)**
- Includes a [sample `.htaccess` file](.htaccess) for caching Javascript and CSS
- Switchable emoji sets **(SOON!)**
- Made from unicorn blood

## Installation

Care about old browsers compatibility? Use https://github.com/es-shims/es5-shim

### Via cdnjs

emojify.js is now available on cdnjs - https://cdnjs.com/libraries/emojify.js

Add this to the rest of your stylesheet imports:

`<link rel="stylesheet" href="//cdnjs.cloudflare.com/ajax/libs/emojify.js/1.0.1/emojify.min.css" />`

Then add this to your Javascript code:

`<script src="//cdnjs.cloudflare.com/ajax/libs/emojify.js/1.0.1/emojify.min.js"></script>`

### Via Bower

`bower install emojify.js --save`

### Via npm

`npm install emojify.js  --save`

## API

### setConfig([object])

*This works in the browser and on Node*

#### Parameters

- `object` - Optional JSON object with any of the following attributes:

Option | Default | Description
--- | --- | ---
`blacklist.elements` | `['script', 'textarea', 'a', 'pre', 'code']` | An array of elements you don't want emojified
`blacklist.classes` | `['no-emojify']` | An array of classes you don't want emojified
`mode` | `img` | By default, emojify will output an `img` with a `src` attribute for each emoji found. But if `mode` is set to `sprite` or `data-uri`, then `span`s with classes are outputted. Don't forget to include the appropriate CSS for your choice though, see the `/dist` directory.
`tag_type` | `null` | When set, emojify uses this element with the class `emoji emoji-#{emojiname}` instead of an `img` with a `src` attribute.  Example valid values: `div`, `span`. This takes precedence over the `mode` option. Note: if you're not using `img`s, `.emoji-+1` isn't a valid class, so `.emoji-plus1` is used instead.
`only_crawl_id` | `null` | **[DEPRECATED]** Restricts searching for emojis to a specified element & it's children. If null, and no object is passed to `run()`, `document.body` is used
`img_dir` | `'images/emoji'` | Defines the path to the emoji images
`ignore_emoticons` | `false` | If `true`, only convert emoji like `:smile:` and ignore emoticons like `:)`

#### Usage
```js
emojify.setConfig({tag_type : 'div'});
```

---

### run([element], [replacer])

*This works in the browser and Node*

#### Parameters
- `element` - Optional HTML element to restrict the emojification to.
- `replacer` - Optional Function to override emoji replacement behaviour with your own. The function will receive two arguments, the emoji pattern found (`emoji`), and the emoji name (`name`). In the case of emoticons, for example, `emoji = ':)'` and `name = 'smile'`. Your function must return a HTMLElement.


##### Browser
```js
emojify.run();
// OR
emojify.run(document.getElementById('my-element'))
// OR
emojify.run(null, function(emoji, emojiName){
  var span = document.createElement('span');
  span.className = 'emoji emoji-'  + emojiName;
  span.innerHTML = emoji + ' replaced';
  return span;
});
```

##### Node.js
Requires you to have jsdom installed:
`npm i jsdom --save`

```js
var jsdom = require('jsdom')

jsdom.env({
    html: "<p><code>jhhh</code><em>:)</em></p>",
    done: function(errors, window) {
        emojify.run(window.document.body)
    }
});
```
---

### replace(string, [callback])

*This works in the browser and on Node*

#### Parameters
- `string` - String to emojify
- `callback` - Optional callback function to output emoji with

#### Usage

By default, emojify.js uses the internal function `defaultReplacer()` to replace emoji. You can override this behaviour by supplying your own callback function.

Your callback function will receive two arguments, the emoji pattern found (`emoji`), and the emoji name (`name`). In the case of emoticons, for example, `emoji = ':)'` and `name = 'smile'`.

The context in which your replacer function is run will have the config available. So you can access properties such as `img_dir` at `this.config.img_dir`.

```js
emojify.replace('I am happy :)');
// OR
replacer = function(emoji, name) {
    // Customise output here
    return emojifiedString;
}

emojify.replace('I am happy :)', replacer);
```

## Contributing changes

Please read [CONTRIBUTING.md](CONTRIBUTING.md).

## Credits

- [All Contributors](https://github.com/hassankhan/emojify.js/contributors)
- [Hassan Khan](https://github.com/hassankhan)

## License

Please read [LICENSE.md](LICENSE.md). For image attributions, please read [LICENSE-IMAGES.md](LICENSE-IMAGES.md)

[travis]: https://travis-ci.org/hassankhan/emojify.js
[appveyor]: https://ci.appveyor.com/project/hassankhan/emojify-js
[package-bower]: http://bower.io/search/?q=emojify.js
[package-npm]: https://www.npmjs.org/package/emojify.js
[ico-build]: http://img.shields.io/travis/hassankhan/emojify.js.svg?style=flat-square
[ico-build-dev]: http://img.shields.io/travis/hassankhan/emojify.js/develop.svg?style=flat-square
[ico-windows-build]: https://ci.appveyor.com/api/projects/status/908bymld8nm3ykxm?svg=true
[ico-windows-build-dev]: https://ci.appveyor.com/api/projects/status/908bymld8nm3ykxm/branch/develop?svg=true
[ico-bower]: http://img.shields.io/bower/v/emojify.js.svg?style=flat-square
[ico-npm]: http://img.shields.io/npm/v/emojify.js.svg?style=flat-square
[ico-license]: http://img.shields.io/npm/l/emojify.js.svg?style=flat-square
[ico-gitter]: https://badges.gitter.im/hassankhan/emojify.js.svg
[license]: http://hassankhan.mit-license.org/
[gitter]: https://gitter.im/hassankhan/emojify.js