Update README
This commit is contained in:
Nikita Karamov
parent
00ac23895f
commit
8b938e59fe
151
README.md
151
README.md
|
|
@ -1,84 +1,98 @@
|
|||
# shareon
|
||||
📯 shareon
|
||||
==========
|
||||
|
||||
<img src="https://raw.githubusercontent.com/NickKaramoff/shareon/main/assets/logo.svg" align="right" alt="shareon logo — the Postal Horn emoji" width="96" height="96">
|
||||
> Lightweight, stylish and ethical share buttons for popular social networks
|
||||
|
||||
> Lightweight, stylish and ethical share buttons
|
||||
<img src="assets/demo@2x.png" height="90" width="395" alt="demo: shareon buttons for various popular social networks">
|
||||
|
||||
- **Small.** Dependency-free. CSS+JS bundle is only 6 KB minified and gzipped.
|
||||
- **Stylish.** Uses official vector logos and colors with no visual mess.
|
||||
- **Small.** Dependency-free. CSS+JS bundle is uner 7 KB, minified and gzipped.
|
||||
- **Stylish.** Uses official colours and vector logos with no visual mess.
|
||||
- **Ethical.** Embeds no tracking code. JS is required only for the setup.
|
||||
|
||||
<img src="https://raw.githubusercontent.com/NickKaramoff/shareon/main/assets/demo@2x.png" height="84" width="392" alt="shareon demo screenshot">
|
||||
Observe the live demo at [shareon.js.org](https://shareon.js.org/)!
|
||||
|
||||
----
|
||||
Observe the live demo here: [shareon.js.org](https://shareon.js.org)
|
||||
Install
|
||||
-------
|
||||
|
||||
## Install
|
||||
### Modern browsers
|
||||
|
||||
shareon ships as an ES6 module.
|
||||
[Most modern browsers](https://caniuse.com/es6-module) support this format.
|
||||
|
||||
Include the link to shareon's JS and CSS in your website:
|
||||
|
||||
```html
|
||||
<link href="https://cdn.jsdelivr.net/npm/shareon@1/dist/shareon.min.css" rel="stylesheet">
|
||||
<script src="https://cdn.jsdelivr.net/npm/shareon@1/dist/shareon.min.js" type="text/javascript"></script>
|
||||
<link href="https://cdn.jsdelivr.net/npm/shareon@2/shareon.css" rel="stylesheet">
|
||||
<script type="module" src="https://cdn.jsdelivr.net/npm/shareon@2"></script>
|
||||
```
|
||||
|
||||
or install it via NPM use it in a JS file that you will bundle:
|
||||
### Older browsers
|
||||
|
||||
If for some reason you don't want to use the ESM format, you can include the
|
||||
Legacy (IIFE) version of the package
|
||||
|
||||
```html
|
||||
<link href="https://cdn.jsdelivr.net/npm/shareon@2/shareon.css" rel="stylesheet">
|
||||
<script src="https://cdn.jsdelivr.net/npm/shareon@2/shareon.legacy.js" type="text/javascript"></script>
|
||||
```
|
||||
|
||||
### Node.js
|
||||
|
||||
If you build a web app using Node.js, you can install shareon as a package:
|
||||
|
||||
```sh
|
||||
npm install shareon
|
||||
# or
|
||||
```
|
||||
|
||||
```sh
|
||||
yarn add shareon
|
||||
```
|
||||
|
||||
Then, import it in your code:
|
||||
|
||||
```js
|
||||
const shareon = require('shareon');
|
||||
// or
|
||||
import shareon from 'shareon';
|
||||
```
|
||||
|
||||
## Initialization
|
||||
> **💡 Tip!** Modern browsers and some bundlers support importing directly from
|
||||
> URL:
|
||||
>
|
||||
> ```js
|
||||
> import shareon from 'https://cdn.jsdelivr.net/npm/shareon@2';
|
||||
> ```
|
||||
|
||||
CommonJS' `require()` [**is not supported**](https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c).
|
||||
|
||||
Initialization
|
||||
--------------
|
||||
|
||||
By default, shareon will initialize every button after page load. It also
|
||||
exports the `shareon` function, that will let you repopulate your buttons with
|
||||
updated information (for example, if you changed the page title):
|
||||
|
||||
```js
|
||||
import shareon from 'shareon';
|
||||
// shareon auto-initializes
|
||||
|
||||
window.title = "Cool new window title";
|
||||
shareon();
|
||||
```
|
||||
|
||||
If you want to postpone the initialization, you can import the `noinit`-version
|
||||
of the package. You'll need to manually call the `shareon` function when you
|
||||
want the buttons to be initialized:
|
||||
If you use the IIFE version, `shareon()` is available as a global function:
|
||||
|
||||
```html
|
||||
<!-- notice the 'noinit' section of the url for JS -->
|
||||
<link href="https://cdn.jsdelivr.net/npm/shareon@1/dist/shareon.min.css" rel="stylesheet">
|
||||
<script src="https://cdn.jsdelivr.net/npm/shareon@1/dist/noinit/shareon.min.js" type="text/javascript"></script>
|
||||
|
||||
<script type="text/javascript">
|
||||
// do something important
|
||||
shareon();
|
||||
<script>
|
||||
window.title = "Cool new window title";
|
||||
window.shareon();
|
||||
</script>
|
||||
```
|
||||
|
||||
or, if you're using Node:
|
||||
Usage
|
||||
-----
|
||||
|
||||
```js
|
||||
const shareon = require('shareon/dist/noinit/shareon');
|
||||
// or
|
||||
import shareon from 'shareon/dist/noinit/shareon';
|
||||
|
||||
// do something important
|
||||
shareon();
|
||||
```
|
||||
|
||||
## Usage
|
||||
|
||||
> shareon was heavily inspired by [Likely](https://ilyabirman.net/projects/likely/),
|
||||
and has a backwards-compatible API (excluding themes and sizes).
|
||||
> shareon was heavily inspired by
|
||||
> [Likely](https://ilyabirman.net/projects/likely/),
|
||||
> and has backwards-compatible networks' names
|
||||
|
||||
Create a container with class `shareon` and populate it with elements, whose
|
||||
classes match the names of social networks:
|
||||
|
|
@ -88,39 +102,45 @@ classes match the names of social networks:
|
|||
<a class="facebook"></a>
|
||||
<a class="linkedin"></a>
|
||||
<a class="mastodon"></a>
|
||||
<!-- FB App ID is required for the Messenger button to function -->
|
||||
|
||||
<!-- App ID is required for the Messenger button to function -->
|
||||
<a class="messenger" data-fb-app-id="0123456789012345"></a>
|
||||
|
||||
<a class="odnoklassniki"></a>
|
||||
<a class="pinterest"></a>
|
||||
<a class="pocket"></a>
|
||||
<button class="reddit"></button>
|
||||
<button class="telegram"></button>
|
||||
<button class="twitter"></button>
|
||||
<button class="viber"></button>
|
||||
<button class="vkontakte"></button>
|
||||
<button class="whatsapp"></button>
|
||||
<a class="reddit"></a>
|
||||
<a class="telegram"></a>
|
||||
<a class="twitter"></a>
|
||||
<a class="viber"></a>
|
||||
<a class="vkontakte"></a>
|
||||
<a class="whatsapp"></a>
|
||||
</div>
|
||||
```
|
||||
|
||||
If you use `<a>`, the buttons will get a `href`-attribute to them. In other cases
|
||||
they will get a listener on `click` event, so you can use `<button>`s if you wish.
|
||||
> The elements don't have to be `<a>`s — if you use a different tag (for example,
|
||||
`<button>`), shareon will use event listeners instead of `href`. Note that this
|
||||
is not the intended use case and is slower.
|
||||
|
||||
By default, the URL and the title of the page will be used in sharing dialogs.
|
||||
To change this, you can use the `data-url` and `data-title` attributes. Use them
|
||||
on the whole container or on the specific buttons:
|
||||
|
||||
```html
|
||||
<div class="shareon" data-url="https://example.com">
|
||||
<a class="facebook" data-title="Custom Facebook title"></a>
|
||||
<a class="twitter" data-title="Custom Twitter title"></a>
|
||||
<div class="shareon" data-url="https://custom.url.com">
|
||||
<a class="facebook" data-title="Custom title for Facebook"></a>
|
||||
<a class="twitter" data-title="Custom title for Twitter"></a>
|
||||
</div>
|
||||
```
|
||||
|
||||
Apart from the URL and title, some networks support extra parameters:
|
||||
Apart from the URL and title, some social networks support extra parameters:
|
||||
|
||||
- you **have to** add `data-fb-app-id` to the FB Messenger button to make sharing even possible
|
||||
- add `data-media` to an Odnoklassniki, Pinterest, or VK button to customize the pinned picture
|
||||
- add `data-text` to a WhatsApp, Mastodon, Telegram, or Viber button to add custom message text
|
||||
- you **MUST** add `data-fb-app-id` to the FB Messenger button to make
|
||||
sharing possible
|
||||
- add `data-media` to an Odnoklassniki, Pinterest, or VK buttons to customize
|
||||
the pinned picture
|
||||
- add `data-text` to a WhatsApp, Mastodon, Telegram, or Viber button to add
|
||||
custom message text
|
||||
- add `data-via` to a Twitter or Mastodon button to mention a user
|
||||
|
||||
Here are all the custom parameters in their glory:
|
||||
|
|
@ -137,13 +157,26 @@ Here are all the custom parameters in their glory:
|
|||
</div>
|
||||
```
|
||||
|
||||
## License
|
||||
Licence
|
||||
-------
|
||||
|
||||
BSD-3-Clause © [Nikita Karamov](https://karamoff.dev)
|
||||
[BSD-3-Clause](https://spdx.org/licenses/BSD-3-Clause.html) © 2020, Nikita Karamov
|
||||
|
||||
shareon logo is the [Postal Horn emoji](https://github.com/googlefonts/noto-emoji/blob/v2020-09-16-unicode13_1/svg/emoji_u1f4ef.svg) from [Noto Emoji](https://github.com/googlefonts/noto-emoji/tree/v2020-09-16-unicode13_1), which is licensed under the [Apache License v2.0](https://github.com/googlefonts/noto-emoji/blob/v2020-09-16-unicode13_1/LICENSE).
|
||||
shareon logo is the
|
||||
[Postal Horn emoji](https://github.com/googlefonts/noto-emoji/blob/v2020-09-16-unicode13_1/svg/emoji_u1f4ef.svg)
|
||||
from
|
||||
[Noto Emoji](https://github.com/googlefonts/noto-emoji/tree/v2020-09-16-unicode13_1),
|
||||
which is licensed under the
|
||||
[Apache License v2.0](https://github.com/googlefonts/noto-emoji/blob/v2020-09-16-unicode13_1/LICENSE).
|
||||
|
||||
Includes a modified version of the
|
||||
[Mastodon logo](https://commons.wikimedia.org/wiki/File:Mastodon_Logotype_%28Simple%29.svg),
|
||||
which is licensed under the
|
||||
[APGLv3 license](https://www.gnu.org/licenses/agpl.html) or later.
|
||||
|
||||
----
|
||||
|
||||
The source code is being hosted
|
||||
on [GitHub](https://github.com/NickKaramoff/shareon) with mirrors
|
||||
on [GitLab](https://gitlab.com/NickKaramoff/shareon)
|
||||
and [Codeberg](https://codeberg.org/NickKaramoff/shareon).
|
||||
|
|
|
|||
Binary file not shown.
|
Before Width: | Height: | Size: 9.5 KiB After Width: | Height: | Size: 15 KiB |
Loading…
Reference in New Issue