From 976a2364bbd8606f6102d98d5560c525df1d3ac3 Mon Sep 17 00:00:00 2001 From: Alan Velasco Date: Thu, 27 Jun 2019 10:48:45 -0700 Subject: [PATCH] Initial split of README into legacy and contributing --- CONTRIBUTING.md | 24 +++- LEGACY.md | 322 ++++++++++++++++++++++++++++++++++++++++++++++++ README.md | 191 ++++++---------------------- 3 files changed, 383 insertions(+), 154 deletions(-) create mode 100644 LEGACY.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index ddc1d075..dcd96f63 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -33,6 +33,26 @@ 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. +## Making Changes + +### Build + +If you'd like to test and/or contribute please follow these instructions. + +```bash +# clone this repo +git clone -b gh-pages https://github.com/twitter/twemoji.git +cd twemoji + +# 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. + ## Pull requests Good pull requests - patches, improvements, new features - are a fantastic @@ -64,5 +84,5 @@ project: 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 + + diff --git a/LEGACY.md b/LEGACY.md new file mode 100644 index 00000000..17b4e57e --- /dev/null +++ b/LEGACY.md @@ -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 `` tag of your HTML document(s): + +```html + +``` + +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 `` 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 ` + ``` -## 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 `` 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 `