mirror of
https://github.com/twitter/twemoji.git
synced 2024-06-15 03:35:16 +00:00
Reorganization and cleanup of README.md (#364)
* Initial split of README into legacy and contributing * Update contributing steps
This commit is contained in:
Alan Velasco
Nathan Downs
parent
dbd85dfccd
commit
0bff51c31b
@ -33,11 +33,28 @@ Contribution enquiries should take place before any significant pull request,
|
||||
otherwise you risk spending a lot of time working on something that we might
|
||||
have good reasons for rejecting.
|
||||
|
||||
## Pull requests
|
||||
## Making Changes
|
||||
|
||||
Good pull requests - patches, improvements, new features - are a fantastic
|
||||
help. They should remain focused in scope and avoid containing unrelated
|
||||
commits.
|
||||
If you'd like to test and/or contribute please follow these instructions.
|
||||
|
||||
[Fork this repo on GitHub](https://github.com/twitter/twemoji.git/fork)
|
||||
|
||||
### Setup
|
||||
|
||||
```bash
|
||||
# clone your fork
|
||||
git clone -b master https://github.com/$YOUR_USERNAME/twemoji.git/
|
||||
cd twemoji
|
||||
|
||||
# install dependencies
|
||||
yarn install
|
||||
|
||||
# Build and test your installation
|
||||
yarn build
|
||||
yarn test
|
||||
```
|
||||
|
||||
### Making changes
|
||||
|
||||
Make sure to adhere to the coding conventions used throughout the codebase
|
||||
(indentation, accurate comments, etc.) and any other requirements (such as test
|
||||
@ -48,21 +65,37 @@ project:
|
||||
|
||||
1. Create a new topic branch to contain your feature, change, or fix:
|
||||
|
||||
2. Commit your changes in logical chunks. Provide clear and explanatory commit
|
||||
> If you'd like to test and/or propose some changes to the latest library version please change the `./scripts/generate` file at its end so that everything will be generated properly once launched.
|
||||
|
||||
1. Commit your changes in logical chunks. Provide clear and explanatory commit
|
||||
messages. Use git's [interactive rebase](https://help.github.com/en/articles/about-git-rebase)
|
||||
feature to tidy up your commits before making them public.
|
||||
|
||||
3. Locally merge (or rebase) the upstream development branch into your topic branch:
|
||||
2. Run `yarn prepublish`. This will do several things:
|
||||
|
||||
4. Push your topic branch up to your fork:
|
||||
1. Ask for the version number (See: [SemVer](https://semver.org/))
|
||||
2. Build the project and put the built assets in `dist/`
|
||||
3. Run the tests
|
||||
4. Move the contents of the `dist/` directory to the `gh-pages` branch
|
||||
5. Place the contents of the `dist/` directory in its correspoding versioned folder.
|
||||
6. Commit the changes and push them to the `gh-pages` branch of your fork.
|
||||
|
||||
5. [Open a Pull Request](http://help.github.com/send-pull-requests/) with a
|
||||
clear title and description.
|
||||
## Pull requests
|
||||
|
||||
Good pull requests - patches, improvements, new features - are a fantastic
|
||||
help. They should remain focused in scope and avoid containing unrelated
|
||||
commits.
|
||||
|
||||
1. Push your topic branch up to your fork: `git push origin my-feature-branch`
|
||||
|
||||
2. [Open a Pull Request](http://help.github.com/send-pull-requests/) with a
|
||||
clear title and description. One for your changes in `master` and another one for
|
||||
your changes in `gh-pages`.
|
||||
|
||||
## License
|
||||
|
||||
By contributing your code:
|
||||
|
||||
You agree to license your contribution under the terms of the MIT (for code) and CC-BY (for graphics) licenses
|
||||
https://github.com/twitter/twemoji/blob/gh-pages/LICENSE
|
||||
https://github.com/twitter/twemoji/blob/gh-pages/LICENSE-GRAPHICS
|
||||
<https://github.com/twitter/twemoji/blob/gh-pages/LICENSE>
|
||||
<https://github.com/twitter/twemoji/blob/gh-pages/LICENSE-GRAPHICS>
|
||||
|
||||
322
LEGACY.md
Normal file
322
LEGACY.md
Normal file
@ -0,0 +1,322 @@
|
||||
# Twemoji Legacy API (V1)
|
||||
|
||||
## Usage
|
||||
|
||||
### CDN Support
|
||||
|
||||
The folks over at [MaxCDN](https://www.maxcdn.com) have graciously provided CDN support.
|
||||
|
||||
Use the following in the `<head>` tag of your HTML document(s):
|
||||
|
||||
```html
|
||||
<script src="https://twemoji.maxcdn.com/1/twemoji.min.js" crossorigin="anonymous"></script>
|
||||
```
|
||||
|
||||
This guarantees that you are using the V1 version of the library.
|
||||
|
||||
### Download
|
||||
|
||||
If instead you want to download a specific version, please look at the `gh-pages` branch, where you will find the built assets for our legacy versions.
|
||||
|
||||
## API
|
||||
|
||||
Following are all the methods exposed in the `twemoji` namespace.
|
||||
|
||||
### twemoji.parse( ... )
|
||||
|
||||
This is the main parsing utility and has 3 overloads per parsing type.
|
||||
|
||||
There are mainly two kinds of parsing: [string parsing](https://github.com/twitter/twemoji#string-parsing) and [DOM parsing](https://github.com/twitter/twemoji#dom-parsing).
|
||||
|
||||
Each of them accepts a callback to generate an image source or an options object with parsing info.
|
||||
|
||||
Here is a walkthrough of all parsing possibilities:
|
||||
|
||||
#### string parsing
|
||||
|
||||
Given a generic string, replaces all emoji with an `<img>` tag.
|
||||
|
||||
While this can be used to inject emoji via image tags in `innerHTML`, please note that this method does not sanitize the string or prevent malicious code from being executed. As an example, if the text contains a `<script>` tag, it **will not** be converted into `<script>` since it's out of this method's scope to prevent these kind of attacks.
|
||||
|
||||
However, for already sanitized strings, this method can be considered safe enough. Please see DOM parsing if security is one of your major concerns.
|
||||
|
||||
```js
|
||||
twemoji.parse('I \u2764\uFE0F emoji!');
|
||||
|
||||
// will produce
|
||||
/*
|
||||
I <img
|
||||
class="emoji"
|
||||
draggable="false"
|
||||
alt="❤️"
|
||||
src="https://twemoji.maxcdn.com/36x36/2764.png"/> emoji!
|
||||
*/
|
||||
```
|
||||
|
||||
##### string parsing + callback
|
||||
|
||||
If a callback is passed, the value of the `src` attribute will be the value returned by the callback.
|
||||
|
||||
```js
|
||||
twemoji.parse(
|
||||
'I \u2764\uFE0F emoji!',
|
||||
function(icon, options, variant) {
|
||||
return '/assets/' + options.size + '/' + icon + '.gif';
|
||||
}
|
||||
);
|
||||
|
||||
// will produce
|
||||
/*
|
||||
I <img
|
||||
class="emoji"
|
||||
draggable="false"
|
||||
alt="❤️"
|
||||
src="/assets/36x36/2764.gif"/> emoji!
|
||||
*/
|
||||
```
|
||||
|
||||
By default, the `options.size` parameter will be the string `"36x36"` and the `variant` will be an optional `\uFE0F` char that is usually ignored by default. If your assets include or distinguish between `\u2764\uFE0F` and `\u2764`, you might want to use such a variable.
|
||||
|
||||
##### string parsing + callback returning `falsy`
|
||||
|
||||
If the callback returns "falsy values" such as `null`, `undefined`, `0`, `false`, or an empty string, nothing will change for that specific emoji.
|
||||
|
||||
```js
|
||||
var i = 0;
|
||||
twemoji.parse(
|
||||
'emoji, m\u2764\uFE0Fn am\u2764\uFE0Fur',
|
||||
function(icon, options, variant) {
|
||||
if (i++ === 0) {
|
||||
return; // no changes made first call
|
||||
}
|
||||
return '/assets/' + icon + options.ext;
|
||||
}
|
||||
);
|
||||
|
||||
// will produce
|
||||
/*
|
||||
emoji, m❤️n am<img
|
||||
class="emoji"
|
||||
draggable="false"
|
||||
alt="❤️"
|
||||
src="/assets/2764.png"/>ur
|
||||
*/
|
||||
```
|
||||
|
||||
##### string parsing + object
|
||||
|
||||
In case an object is passed as second parameter, the passed `options` object will reflect its properties.
|
||||
|
||||
```js
|
||||
twemoji.parse(
|
||||
'I \u2764\uFE0F emoji!',
|
||||
{
|
||||
callback: function(icon, options) {
|
||||
return '/assets/' + options.size + '/' + icon + '.gif';
|
||||
},
|
||||
size: 128
|
||||
}
|
||||
);
|
||||
|
||||
// will produce
|
||||
/*
|
||||
I <img
|
||||
class="emoji"
|
||||
draggable="false"
|
||||
alt="❤️"
|
||||
src="/assets/128x128/2764.gif"/> emoji!
|
||||
*/
|
||||
```
|
||||
|
||||
#### DOM parsing
|
||||
|
||||
In contrast to `string` parsing, if the first argument is an `HTMLElement`, generated image tags will replace emoji that are **inside `#text` nodes only** without compromising surrounding nodes or listeners, and completely avoiding the usage of `innerHTML`.
|
||||
|
||||
If security is a major concern, this parsing can be considered the safest option but with a slight performance penalty due to DOM operations that are inevitably *costly*.
|
||||
|
||||
```js
|
||||
var div = document.createElement('div');
|
||||
div.textContent = 'I \u2764\uFE0F emoji!';
|
||||
document.body.appendChild(div);
|
||||
|
||||
twemoji.parse(document.body);
|
||||
|
||||
var img = div.querySelector('img');
|
||||
|
||||
// note the div is preserved
|
||||
img.parentNode === div; // true
|
||||
|
||||
img.src; // https://twemoji.maxcdn.com/36x36/2764.png
|
||||
img.alt; // \u2764\uFE0F
|
||||
img.className; // emoji
|
||||
img.draggable; // false
|
||||
|
||||
```
|
||||
|
||||
All other overloads described for `string` are available in exactly the same way for DOM parsing.
|
||||
|
||||
### Object as parameter
|
||||
|
||||
Here's the list of properties accepted by the optional object that can be passed to the `parse` function.
|
||||
|
||||
```js
|
||||
{
|
||||
callback: Function, // default the common replacer
|
||||
attributes: Function, // default returns {}
|
||||
base: string, // default MaxCDN
|
||||
ext: string, // default ".png"
|
||||
className: string, // default "emoji"
|
||||
size: string|number, // default "36x36"
|
||||
folder: string // in case it's specified
|
||||
// it replaces .size info, if any
|
||||
}
|
||||
```
|
||||
|
||||
#### callback
|
||||
|
||||
The function to invoke in order to generate image `src`(s).
|
||||
|
||||
By default it is a function like the following one:
|
||||
|
||||
```js
|
||||
function imageSourceGenerator(icon, options) {
|
||||
return ''.concat(
|
||||
options.base, // by default Twitter Inc. CDN
|
||||
options.size, // by default "36x36" string
|
||||
'/',
|
||||
icon, // the found emoji as code point
|
||||
options.ext // by default ".png"
|
||||
);
|
||||
}
|
||||
```
|
||||
|
||||
#### attributes
|
||||
|
||||
The function to invoke in order to generate additional, custom attributes for the image tag.
|
||||
|
||||
By default it is a function like the following one:
|
||||
|
||||
```js
|
||||
function attributesCallback(icon, variant) {
|
||||
return {
|
||||
title: 'Emoji: ' + icon + variant
|
||||
};
|
||||
}
|
||||
```
|
||||
|
||||
Event handlers cannot be specified via this method, and twemoji-provided attributes (src, alt, className, draggable) cannot be re-defined.
|
||||
|
||||
#### base
|
||||
|
||||
The default url is the same as `twemoji.base`, so if you modify the former, it will reflect as default for all parsed strings or nodes.
|
||||
|
||||
#### ext
|
||||
|
||||
The default image extension is the same as `twemoji.ext` which is `".png"`.
|
||||
|
||||
If you modify the former, it will reflect as default for all parsed strings or nodes.
|
||||
|
||||
#### className
|
||||
|
||||
The default `class` for each generated image is `emoji`. It is possible to specify a different one through this property.
|
||||
|
||||
#### size
|
||||
|
||||
The default asset size is the same as `twemoji.size` which is `"36x36"`.
|
||||
|
||||
If you modify the former, it will reflect as default for all parsed strings or nodes.
|
||||
|
||||
#### folder
|
||||
|
||||
In case you don't want to specify a size for the image. It is possible to choose a folder, as in the case of SVG emoji.
|
||||
|
||||
```js
|
||||
twemoji.parse(genericNode, {
|
||||
folder: 'svg',
|
||||
ext: '.svg'
|
||||
});
|
||||
```
|
||||
|
||||
This will generate urls such `https://twemoji.maxcdn.com/svg/2764.svg` instead of using a specific size based image.
|
||||
|
||||
## Utilities
|
||||
|
||||
Basic utilities / helpers to convert code points to JavaScript surrogates and vice versa.
|
||||
|
||||
### twemoji.convert.fromCodePoint()
|
||||
|
||||
For a given HEX codepoint, returns UTF-16 surrogate pairs.
|
||||
|
||||
```js
|
||||
twemoji.convert.fromCodePoint('1f1e8');
|
||||
// "\ud83c\udde8"
|
||||
```
|
||||
|
||||
### twemoji.convert.toCodePoint()
|
||||
|
||||
For given UTF-16 surrogate pairs, returns the equivalent HEX codepoint.
|
||||
|
||||
```js
|
||||
twemoji.convert.toCodePoint('\ud83c\udde8\ud83c\uddf3');
|
||||
// "1f1e8-1f1f3"
|
||||
|
||||
twemoji.convert.toCodePoint('\ud83c\udde8\ud83c\uddf3', '~');
|
||||
// "1f1e8~1f1f3"
|
||||
```
|
||||
|
||||
## Tips
|
||||
|
||||
### Inline Styles
|
||||
|
||||
If you'd like to size the emoji according to the surrounding text, you can add the following CSS to your stylesheet:
|
||||
|
||||
```css
|
||||
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 set must be set to UTF-8. This can done by including the following meta tag in the document `<head>`
|
||||
|
||||
```html
|
||||
<meta charset="utf-8">
|
||||
```
|
||||
|
||||
### Exclude Characters
|
||||
|
||||
To exclude certain characters from being replaced by twemoji.js, call twemoji.parse() with a callback, returning false for the specific unicode icon. For example:
|
||||
|
||||
```js
|
||||
twemoji.parse(document.body, {
|
||||
callback: function(icon, options, variant) {
|
||||
switch ( icon ) {
|
||||
case 'a9': // © copyright
|
||||
case 'ae': // ® registered trademark
|
||||
case '2122': // ™ trademark
|
||||
return false;
|
||||
}
|
||||
return ''.concat(options.base, options.size, '/', icon, options.ext);
|
||||
}
|
||||
});
|
||||
```
|
||||
|
||||
## Breaking changes in V2
|
||||
|
||||
_TL;DR_: there's no `variant` anymore, all callbacks receive the transformed `iconId` and in some cases the rawText too.
|
||||
|
||||
There are a few potentially breaking changes in `twemoji` version 2:
|
||||
|
||||
* the `parse` invoked function signature is now `(iconId, options)` instead of `(icon, options, variant)`
|
||||
* the `attributes` function now receives `(rawText, iconId)` instead of `(icon, variant)`
|
||||
* the **default** remote protocol is now **https** regardless of whether the current site is _http_ or even _file_
|
||||
* the **default** PNG icon size is **72** pixels and **there are no other PNG assets** for 16 or 32.
|
||||
* in order to access latest assets you need to specify *folder* `2/72x72` or `2/svg`.
|
||||
|
||||
Everything else is pretty much the same, so if you were using the defaults, all you need to do is to add the version `2/` before the `twemoji.js` file you were using.
|
||||
189
README.md
189
README.md
@ -6,34 +6,23 @@ A simple library that provides standard Unicode [emoji](http://en.wikipedia.org/
|
||||
|
||||
The Twemoji library offers support for **3,075** emojis.
|
||||
|
||||
#### Please note
|
||||
The files in the root folder in this project are deprecated and listed for CDN and historical reasons.
|
||||
## Usage
|
||||
|
||||
Please use the files for the current version (2) instead, located under the folder `./2/`.
|
||||
|
||||
## CDN Support
|
||||
### CDN Support
|
||||
|
||||
The folks over at [MaxCDN](https://www.maxcdn.com) have graciously provided CDN support.
|
||||
|
||||
Use the following in the `<head>` tag of your HTML document(s):
|
||||
|
||||
```html
|
||||
<script src="https://twemoji.maxcdn.com/v/latest/twemoji.min.js" crossorigin="anonymous"></script>
|
||||
```
|
||||
|
||||
## Breaking changes in V2
|
||||
This guarantees that you will always use the latest version of the library.
|
||||
|
||||
_TL;DR_: there's no `variant` anymore, all callbacks receive the transformed `iconId` and in some cases the rawText too.
|
||||
|
||||
There are a few potentially breaking changes in `twemoji` version 2:
|
||||
|
||||
* the `parse` invoked function signature is now `(iconId, options)` instead of `(icon, options, variant)`
|
||||
* the `attributes` function now receives `(rawText, iconId)` instead of `(icon, variant)`
|
||||
* the **default** remote protocol is now **https** regardless of whether the current site is _http_ or even _file_
|
||||
* the **default** PNG icon size is **72** pixels and **there are no other PNG assets** for 16 or 32.
|
||||
* in order to access latest assets you need to specify *folder* `2/72x72` or `2/svg`.
|
||||
|
||||
Everything else is pretty much the same, so if you were using the defaults, all you need to do is to add the version `2/` before the `twemoji.js` file you were using.
|
||||
### Download
|
||||
|
||||
If instead you want to download a specific version, please look at the `gh-pages` branch, where you will find the built assets for both our latest and older versions.
|
||||
|
||||
## API
|
||||
|
||||
@ -49,99 +38,7 @@ Each of them accepts a callback to generate an image source or an options object
|
||||
|
||||
Here is a walkthrough of all parsing possibilities:
|
||||
|
||||
##### string parsing (V1)
|
||||
Given a generic string, replaces all emoji with an `<img>` tag.
|
||||
|
||||
While this can be used to inject emoji via image tags in `innerHTML`, please note that this method does not sanitize the string or prevent malicious code from being executed. As an example, if the text contains a `<script>` tag, it **will not** be converted into `<script>` since it's out of this method's scope to prevent these kind of attacks.
|
||||
|
||||
However, for already sanitized strings, this method can be considered safe enough. Please see DOM parsing if security is one of your major concerns.
|
||||
|
||||
```js
|
||||
twemoji.parse('I \u2764\uFE0F emoji!');
|
||||
|
||||
// will produce
|
||||
/*
|
||||
I <img
|
||||
class="emoji"
|
||||
draggable="false"
|
||||
alt="❤️"
|
||||
src="https://twemoji.maxcdn.com/36x36/2764.png"/> emoji!
|
||||
*/
|
||||
```
|
||||
|
||||
_string parsing + callback_
|
||||
|
||||
If a callback is passed, the value of the `src` attribute will be the value returned by the callback.
|
||||
```js
|
||||
twemoji.parse(
|
||||
'I \u2764\uFE0F emoji!',
|
||||
function(icon, options, variant) {
|
||||
return '/assets/' + options.size + '/' + icon + '.gif';
|
||||
}
|
||||
);
|
||||
|
||||
// will produce
|
||||
/*
|
||||
I <img
|
||||
class="emoji"
|
||||
draggable="false"
|
||||
alt="❤️"
|
||||
src="/assets/36x36/2764.gif"/> emoji!
|
||||
*/
|
||||
```
|
||||
|
||||
By default, the `options.size` parameter will be the string `"36x36"` and the `variant` will be an optional `\uFE0F` char that is usually ignored by default. If your assets include or distinguish between `\u2764\uFE0F` and `\u2764`, you might want to use such a variable.
|
||||
|
||||
_string parsing + callback returning_ `falsy`
|
||||
|
||||
If the callback returns "falsy values" such as `null`, `undefined`, `0`, `false`, or an empty string, nothing will change for that specific emoji.
|
||||
```js
|
||||
var i = 0;
|
||||
twemoji.parse(
|
||||
'emoji, m\u2764\uFE0Fn am\u2764\uFE0Fur',
|
||||
function(icon, options, variant) {
|
||||
if (i++ === 0) {
|
||||
return; // no changes made first call
|
||||
}
|
||||
return '/assets/' + icon + options.ext;
|
||||
}
|
||||
);
|
||||
|
||||
// will produce
|
||||
/*
|
||||
emoji, m❤️n am<img
|
||||
class="emoji"
|
||||
draggable="false"
|
||||
alt="❤️"
|
||||
src="/assets/2764.png"/>ur
|
||||
*/
|
||||
```
|
||||
|
||||
_string parsing + object_
|
||||
|
||||
In case an object is passed as second parameter, the passed `options` object will reflect its properties.
|
||||
```js
|
||||
twemoji.parse(
|
||||
'I \u2764\uFE0F emoji!',
|
||||
{
|
||||
callback: function(icon, options) {
|
||||
return '/assets/' + options.size + '/' + icon + '.gif';
|
||||
},
|
||||
size: 128
|
||||
}
|
||||
);
|
||||
|
||||
// will produce
|
||||
/*
|
||||
I <img
|
||||
class="emoji"
|
||||
draggable="false"
|
||||
alt="❤️"
|
||||
src="/assets/128x128/2764.gif"/> emoji!
|
||||
*/
|
||||
```
|
||||
|
||||
##### DOM parsing
|
||||
#### DOM parsing
|
||||
|
||||
In contrast to `string` parsing, if the first argument is an `HTMLElement`, generated image tags will replace emoji that are **inside `#text` nodes only** without compromising surrounding nodes or listeners, and completely avoiding the usage of `innerHTML`.
|
||||
|
||||
@ -169,6 +66,7 @@ img.draggable; // false
|
||||
All other overloads described for `string` are available in exactly the same way for DOM parsing.
|
||||
|
||||
### Object as parameter
|
||||
|
||||
Here's the list of properties accepted by the optional object that can be passed to the `parse` function.
|
||||
|
||||
```js
|
||||
@ -184,10 +82,12 @@ Here's the list of properties accepted by the optional object that can be passed
|
||||
}
|
||||
```
|
||||
|
||||
##### callback
|
||||
#### callback
|
||||
|
||||
The function to invoke in order to generate image `src`(s).
|
||||
|
||||
By default it is a function like the following one:
|
||||
|
||||
```js
|
||||
function imageSourceGenerator(icon, options) {
|
||||
return ''.concat(
|
||||
@ -200,62 +100,56 @@ function imageSourceGenerator(icon, options) {
|
||||
}
|
||||
```
|
||||
|
||||
##### attributes (V1)
|
||||
The function to invoke in order to generate additional, custom attributes for the image tag.
|
||||
#### base
|
||||
|
||||
By default it is a function like the following one:
|
||||
```js
|
||||
function attributesCallback(icon, variant) {
|
||||
return {
|
||||
title: 'Emoji: ' + icon + variant
|
||||
};
|
||||
}
|
||||
```
|
||||
|
||||
Event handlers cannot be specified via this method, and twemoji-provided attributes (src, alt, className, draggable) cannot be re-defined.
|
||||
|
||||
##### base
|
||||
The default url is the same as `twemoji.base`, so if you modify the former, it will reflect as default for all parsed strings or nodes.
|
||||
|
||||
#### ext
|
||||
|
||||
##### ext
|
||||
The default image extension is the same as `twemoji.ext` which is `".png"`.
|
||||
|
||||
If you modify the former, it will reflect as default for all parsed strings or nodes.
|
||||
|
||||
#### className
|
||||
|
||||
##### className
|
||||
The default `class` for each generated image is `emoji`. It is possible to specify a different one through this property.
|
||||
|
||||
|
||||
##### size
|
||||
|
||||
The default asset size is the same as `twemoji.size` which is `"36x36"`.
|
||||
|
||||
If you modify the former, it will reflect as default for all parsed strings or nodes.
|
||||
|
||||
#### folder
|
||||
|
||||
##### folder
|
||||
In case you don't want to specify a size for the image. It is possible to choose a folder, as in the case of SVG emoji.
|
||||
|
||||
```js
|
||||
twemoji.parse(genericNode, {
|
||||
folder: 'svg',
|
||||
ext: '.svg'
|
||||
});
|
||||
```
|
||||
|
||||
This will generate urls such `https://twemoji.maxcdn.com/svg/2764.svg` instead of using a specific size based image.
|
||||
|
||||
## Utilities
|
||||
|
||||
Basic utilities / helpers to convert code points to JavaScript surrogates and vice versa.
|
||||
|
||||
#### twemoji.convert.fromCodePoint()
|
||||
### twemoji.convert.fromCodePoint()
|
||||
|
||||
For a given HEX codepoint, returns UTF-16 surrogate pairs.
|
||||
|
||||
```js
|
||||
twemoji.convert.fromCodePoint('1f1e8');
|
||||
// "\ud83c\udde8"
|
||||
```
|
||||
#### twemoji.convert.toCodePoint()
|
||||
|
||||
### twemoji.convert.toCodePoint()
|
||||
|
||||
For given UTF-16 surrogate pairs, returns the equivalent HEX codepoint.
|
||||
|
||||
```js
|
||||
twemoji.convert.toCodePoint('\ud83c\udde8\ud83c\uddf3');
|
||||
// "1f1e8-1f1f3"
|
||||
@ -266,11 +160,11 @@ For given UTF-16 surrogate pairs, returns the equivalent HEX codepoint.
|
||||
|
||||
## Tips
|
||||
|
||||
#### Inline Styles
|
||||
### Inline Styles
|
||||
|
||||
If you'd like to size the emoji according to the surrounding text, you can add the following CSS to your stylesheet:
|
||||
|
||||
```
|
||||
```css
|
||||
img.emoji {
|
||||
height: 1em;
|
||||
width: 1em;
|
||||
@ -281,7 +175,7 @@ img.emoji {
|
||||
|
||||
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
|
||||
### UTF-8 Character Set
|
||||
|
||||
To properly support emoji, the document character set must be set to UTF-8. This can done by including the following meta tag in the document `<head>`
|
||||
|
||||
@ -289,7 +183,7 @@ To properly support emoji, the document character set must be set to UTF-8. This
|
||||
<meta charset="utf-8">
|
||||
```
|
||||
|
||||
#### Exclude Characters (V1)
|
||||
### Exclude Characters (V1)
|
||||
|
||||
To exclude certain characters from being replaced by twemoji.js, call twemoji.parse() with a callback, returning false for the specific unicode icon. For example:
|
||||
|
||||
@ -307,23 +201,13 @@ twemoji.parse(document.body, {
|
||||
});
|
||||
```
|
||||
|
||||
### Build
|
||||
If you'd like to test and/or contribute please follow these instructions.
|
||||
## Legacy API (V1)
|
||||
|
||||
```bash
|
||||
# clone this repo
|
||||
git clone -b gh-pages https://github.com/twitter/twemoji.git
|
||||
cd twemoji
|
||||
If you're still using our V1 API, you can read our legacy documentation [here](https://github.com/twitter/twemoji/tree/master/LEGACY.md).
|
||||
|
||||
# install dependencies
|
||||
yarn install
|
||||
|
||||
# generate 2/twemoji*.js files
|
||||
./2/scripts/generate
|
||||
```
|
||||
|
||||
If you'd like to test and/or propose some changes to the V2 library please change the `./2/scripts/generate` file at its end so that everything will be generated properly once launched.
|
||||
## Contributing
|
||||
|
||||
The contributing documentation can be found [here](https://github.com/twitter/twemoji/tree/master/CONTRIBUTING.md).
|
||||
|
||||
## Attribution Requirements
|
||||
|
||||
@ -332,6 +216,7 @@ As an open source project, attribution is critical from a legal, practical and m
|
||||
However, we consider the guide a bit onerous and as a project, will accept a mention in a project README or an 'About' section or footer on a website. In mobile applications, a common place would be in the Settings/About section (for example, see the mobile Twitter application Settings->About->Legal section). We would consider a mention in the HTML/JS source sufficient also.
|
||||
|
||||
## Community Projects
|
||||
|
||||
* [Twemoji Amazing](https://github.com/SebastianAigner/twemoji-amazing) by [@SebastianAigner](https://github.com/SebastianAigner): Use Twemoji using CSS classes (like [Font Awesome](http://fortawesome.github.io/Font-Awesome/)).
|
||||
* [Twemoji Ruby](https://github.com/jollygoodcode/twemoji) by [@JollyGoodCode](https://twitter.com/jollygoodcode): Use Twemoji in Ruby.
|
||||
* [Twemoji for Pencil](https://github.com/nathanielw/Twemoji-for-Pencil) by [@Nathanielnw](https://twitter.com/nathanielnw): Use Twemoji in Pencil.
|
||||
@ -343,6 +228,7 @@ However, we consider the guide a bit onerous and as a project, will accept a men
|
||||
* [Unmaintained] [Twemoji Awesome](http://ellekasai.github.io/twemoji-awesome/) by [@ellekasai](https://twitter.com/ellekasai/): Use Twemoji using CSS classes (like [Font Awesome](http://fortawesome.github.io/Font-Awesome/)).
|
||||
|
||||
## Committers and Contributors
|
||||
|
||||
* Bryan Haggerty (Twitter)
|
||||
* Nathan Downs (Twitter)
|
||||
* Tom Wuttke (ex-Twitter)
|
||||
@ -357,8 +243,9 @@ The rules for contributing are available in the `CONTRIBUTING.md` file.
|
||||
Thank you to all of our [contributors](https://github.com/twitter/twemoji/graphs/contributors).
|
||||
|
||||
## License
|
||||
|
||||
Copyright 2019 Twitter, Inc and other contributors
|
||||
|
||||
Code licensed under the MIT License: http://opensource.org/licenses/MIT
|
||||
Code licensed under the MIT License: <http://opensource.org/licenses/MIT>
|
||||
|
||||
Graphics licensed under CC-BY 4.0: https://creativecommons.org/licenses/by/4.0/
|
||||
Graphics licensed under CC-BY 4.0: <https://creativecommons.org/licenses/by/4.0/>
|
||||
|
||||
Loading…
Reference in New Issue
Block a user