earnestma
/
shareon
1
0
Fork 0
Code Issues Pull Requests Releases Activity

Update README 

- update installation instruction

 - use clearer text for descriptions

 - update licence footer; add information about Simple Icons

 - update URLs and permalinks to related projects
pull/45/head
Nikita Karamov 2022-02-11 14:26:45 +01:00
parent 6e4ec8ea26
commit 2877fef357
No known key found for this signature in database
GPG Key ID: 3C8E688C96EEB9C9
1 changed files with 101 additions and 87 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

188
README.md
View File

@ -1,100 +1,92 @@
# shareon
# Shareon
<img src="./assets/logo.svg" align="right" alt="shareon logo — the Postal Horn emoji" width="96" height="96">
<img src="./assets/logo.svg" align="right" alt="Shareon logo — the Postal Horn emoji" width="96" height="96">
> Lightweight, stylish and ethical share buttons
> Lightweight, stylish, and ethical share buttons
- **Small.** Dependency-free. CSS+JS bundle is only 6 KB minified and gzipped.
- **Stylish.** Uses official vector logos and colors with no visual mess.
- **Stylish.** Uses official vector logos and colours with no visual mess.
- **Ethical.** Embeds no tracking code. JS is required only for the setup.
<img src="./assets/demo@2x.png" height="84" width="390" alt="shareon demo screenshot">
<a href="https://shareon.js.org/"><img src="./assets/demo@2x.png" height="84" width="390" alt="Shareon demo screenshot"></a>
---
Observe the live demo here: [shareon.js.org](https://shareon.js.org)
See the live demo at [shareon.js.org](https://shareon.js.org)
## Install
Include the link to shareon's JS and CSS in your website:
Simply load the needed files from the CDN:
```html
<link
href="https://cdn.jsdelivr.net/npm/shareon@1/dist/shareon.min.css"
href="https://cdn.jsdelivr.net/npm/shareon@2/dist/shareon.min.css"
rel="stylesheet"
/>
<script
src="https://cdn.jsdelivr.net/npm/shareon@1/dist/shareon.min.js"
type="text/javascript"
src="https://cdn.jsdelivr.net/npm/shareon@2/dist/shareon.iife.js"
defer
init
></script>
```
or install it via NPM use it in a JS file that you will bundle:
- `defer` makes sure Shareon is loaded after HTML is parsed
- `init` will automatically initialize Shareon buttons
```sh
npm install shareon
# or
yarn add shareon
```
### Do not auto-initialize
```js
const shareon = require("shareon");
// or
import shareon from "shareon";
```
## 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
// 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:
Remove the `init` attribute and initialize Shareon when you need it:
```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"
src="https://cdn.jsdelivr.net/npm/shareon@2/dist/shareon.iife.js"
defer
></script>
<script type="text/javascript">
// do something important
shareon();
<script>
// do something
Shareon.init();
</script>
```
or, if you're using Node:
### Use ESM build
There is also a ESM build for the browsers, which doesn't support
auto-initialization:
```html
<script type="module">
import { init } from "https://cdn.jsdelivr.net/npm/shareon@2/dist/shareon.es.js";
// do something
init();
</script>
```
### Bundle with Node
You can also install Shareon using your favourite package manager and include it
in your source files:
```sh
pnpm add shareon # or `npm install`, or `yarn add`
```
```js
const shareon = require("shareon/dist/noinit/shareon");
// or
import shareon from "shareon/dist/noinit/shareon";
import { init } from "shareon";
// do something important
shareon();
init();
```
CommonJS imports are also supported:
```js
const Shareon = require("shareon");
Shareon.init();
```
## Usage
> shareon was heavily inspired by [Likely](https://ilyabirman.net/projects/likely/),
> and has a backwards-compatible API (excluding themes and sizes).
Create a container with class `shareon` and populate it with elements, whose
classes match the names of social networks:
Create a container with class `shareon` and populate it with elements, class
names of which match the names of the social networks:
```html
<div class="shareon">
@ -106,24 +98,31 @@ classes match the names of social networks:
<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.
Shareon will populate these `<a>` elements with correct `href` attributes.
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:
### Use with `<button>`s
You can use `<button>` (or any other element) instead of `<a>`s. In this case,
Shareon will create an `onclick`-listener for each button. **I do not recommend
doing this**, as this is not so good for semantics.
### Share metadata
By default, the URL and the title of the active page will be shared. You can
customize it with `data-` attributes. These can be applied on a specific button
or on the whole `.shareon` container:
```html
<div class="shareon" data-url="https://example.com">
<div class="shareon" data-url="https://custom.url/for-this-page">
<a class="facebook" data-title="Custom Facebook title"></a>
<a class="twitter" data-title="Custom Twitter title"></a>
</div>
@ -131,32 +130,47 @@ on the whole container or on the specific buttons:
Apart from the URL and title, some 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
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
- add `data-via` to a Twitter or Mastodon button to mention a user
Here are all the custom parameters in their glory:
Here are all custom parameters:
```html
<div class="shareon" data-url="https://example.com/custom-url">
<div class="shareon" data-url="https://custom.url/for-this-page">
<a class="facebook" data-title="Custom Facebook title"></a>
<a class="messenger" data-fb-app-id="0123456789012345"></a>
<a class="pinterest" data-media="https://picsum.photos/500">Pin</a>
<a class="pinterest" data-media="https://custom.picture/for-pinterest">Pin</a>
<a class="telegram" data-text="Check this out!"></a>
<a class="twitter" data-via="MyNickname"></a>
<a class="mastodon" data-via="@MyNickname@myserver.social"></a>
<a class="whatsapp" data-url="https://my-cool-website.com">Send</a>
<a class="whatsapp" data-url="https://custom.url/for-whatsapp">Send</a>
</div>
```
## License
## Licence
MIT © [Nikita Karamov](https://www.kytta.dev/)
Copyright © 2020–2022 [Nikita Karamov](https://www.kytta.dev/)
Licenced under the [MIT License](https://spdx.org/licenses/MIT.html).
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 was heavily inspired by [Likely](https://ilyabirman.net/likely/),
and has a somewhat backwards-compatible API (excluding themes and sizes).
Likely is licenced under the MIT 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.
Shareon's logo is the
[Postal Horn emoji](https://github.com/googlefonts/noto-emoji/blob/43f47be9404018cd9d8f73a227363a8f20acdab5/svg/emoji_u1f4ef.svg)
from [Noto Emoji](https://github.com/googlefonts/noto-emoji).
Noto Emoji is licenced under the
[Apache License v2.0](https://github.com/googlefonts/noto-emoji/blob/43f47be9404018cd9d8f73a227363a8f20acdab5/LICENSE).
Share icons are being sourced from [Simple Icons](https://github.com/simple-icons/simple-icons/).
Simple Icons is released under [CC0](https://spdx.org/licenses/CC0-1.0.html),
but the icons themselves may be subject to copyright of the respective owners.
---
This project is hosted on Codeberg: <https://codeberg.org/kytta/shareon>