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. - **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. - **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>
--- See 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
Include the link to shareon's JS and CSS in your website: Simply load the needed files from the CDN:
```html ```html
<link <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" rel="stylesheet"
/> />
<script <script
src="https://cdn.jsdelivr.net/npm/shareon@1/dist/shareon.min.js" src="https://cdn.jsdelivr.net/npm/shareon@2/dist/shareon.iife.js"
type="text/javascript" defer
init
></script> ></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 ### Do not auto-initialize
npm install shareon
# or
yarn add shareon
```
```js Remove the `init` attribute and initialize Shareon when you need it:
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:
```html ```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 <script
src="https://cdn.jsdelivr.net/npm/shareon@1/dist/noinit/shareon.min.js" src="https://cdn.jsdelivr.net/npm/shareon@2/dist/shareon.iife.js"
type="text/javascript" defer
></script> ></script>
<script type="text/javascript"> <script>
// do something important // do something
shareon(); Shareon.init();
</script> </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 ```js
const shareon = require("shareon/dist/noinit/shareon"); import { init } from "shareon";
// or
import shareon from "shareon/dist/noinit/shareon";
// do something important init();
shareon(); ```
CommonJS imports are also supported:
```js
const Shareon = require("shareon");
Shareon.init();
``` ```
## Usage ## Usage
> shareon was heavily inspired by [Likely](https://ilyabirman.net/projects/likely/), Create a container with class `shareon` and populate it with elements, class
> and has a backwards-compatible API (excluding themes and sizes). names of which match the names of the social networks:
Create a container with class `shareon` and populate it with elements, whose
classes match the names of social networks:
```html ```html
<div class="shareon"> <div class="shareon">
@ -106,24 +98,31 @@ classes match the names of social networks:
<a class="odnoklassniki"></a> <a class="odnoklassniki"></a>
<a class="pinterest"></a> <a class="pinterest"></a>
<a class="pocket"></a> <a class="pocket"></a>
<button class="reddit"></button> <a class="reddit"></a>
<button class="telegram"></button> <a class="telegram"></a>
<button class="twitter"></button> <a class="twitter"></a>
<button class="viber"></button> <a class="viber"></a>
<button class="vkontakte"></button> <a class="vkontakte"></a>
<button class="whatsapp"></button> <a class="whatsapp"></a>
</div> </div>
``` ```
If you use `<a>`, the buttons will get a `href`-attribute to them. In other cases Shareon will populate these `<a>` elements with correct `href` attributes.
they will get a listener on `click` event, so you can use `<button>`s if you wish.
By default, the URL and the title of the page will be used in sharing dialogs. ### Use with `<button>`s
To change this, you can use the `data-url` and `data-title` attributes. Use them
on the whole container or on the specific buttons: 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 ```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="facebook" data-title="Custom Facebook title"></a>
<a class="twitter" data-title="Custom Twitter title"></a> <a class="twitter" data-title="Custom Twitter title"></a>
</div> </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: 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 - you **MUST** add `data-fb-app-id` to the FB Messenger button to make sharing
- add `data-media` to an Odnoklassniki, Pinterest, or VK button to customize the pinned picture even possible
- add `data-text` to a WhatsApp, Mastodon, Telegram, or Viber button to add custom message text - 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 - 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 ```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="facebook" data-title="Custom Facebook title"></a>
<a class="messenger" data-fb-app-id="0123456789012345"></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="telegram" data-text="Check this out!"></a>
<a class="twitter" data-via="MyNickname"></a> <a class="twitter" data-via="MyNickname"></a>
<a class="mastodon" data-via="@MyNickname@myserver.social"></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> </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 Shareon's logo is the
[Mastodon logo](https://commons.wikimedia.org/wiki/File:Mastodon_Logotype_%28Simple%29.svg), [Postal Horn emoji](https://github.com/googlefonts/noto-emoji/blob/43f47be9404018cd9d8f73a227363a8f20acdab5/svg/emoji_u1f4ef.svg)
which is licensed under the from [Noto Emoji](https://github.com/googlefonts/noto-emoji).
[APGLv3 license](https://www.gnu.org/licenses/agpl.html) or later. 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>