Skip to content

README_V4.MD

Latest commit

 

History

History
369 lines (279 loc) · 13.6 KB

README_V4.MD

File metadata and controls

369 lines (279 loc) · 13.6 KB

Angular Share Buttons v4.1.4

Capture

Demo NPM Build Status LICENSE

NOTE: This version 4.1.4 supports Angular 5 only

Table of contents

Available share buttons:

Facebook, Twitter, Pinterest, Whatsapp, Google, Tumbler, Reddit, StumbleUpOn, LinkedIn

Installation

  1. Install the library npm install ngx-sharebuttons --save

  2. Install font-awesome icons npm install font-awesome --save or use a FontAwesome CDN

  3. Choose the module:

    • ShareButtonsModule for <share-buttons></share-buttons>
    • ShareButtonModule for <share-button [button]="buttonName"></share-button>
    • ShareDirectiveModule for <button [shareButton]="buttonName"></button>
import { ShareButtonsModule } from 'ngx-sharebuttons';

@NgModule({
  imports: [
    HttpClientModule,      // (Required) for share counts
    HttpClientJsonpModule, // (Optional) For linkedIn & Tumblr counts
    ShareButtonsModule.forRoot()
  ]
})
  1. If you want to use the components, import the core styles and the theme from the global style src/styles.scss
/** Import Fontawesome icons */
@import '~font-awesome/css/font-awesome.min.css';

/** Import core style */
@import "~ngx-sharebuttons/styles/share-buttons";

/** Import a theme */
@import "~ngx-sharebuttons/styles/themes/circles/circles-theme";

Share button directive

Convert any element to a share button using the directive [shareButton].

A very basic example:

<button shareButton="facebook"><i class="fa fa-facebook"></i></button>

Material example:

<button md-raised-button shareButton="twitter"><i class="fa fa-twitter"></i></button>
<button md-icon-button shareButton="linkedin"><i class="fa fa-linkedin"></i></button>

You can get the button text and icon from ShareButtons Service

import { ShareButtons } from 'ngx-sharebuttons';

@Component({
  // ...
})
export class MyComponent {
  constructor(public share: ShareButtons) {
  }
}

Now you can set them

<button md-fab shareButton="twitter" [style.backgroundColor]="share.meta.twitter.color">
  <i [class]="share.meta.twitter.icon"></i>
</button>
<button md-fab shareButton="linkedin" [style.color]="share.meta.linkedin.color">
  <i [class]="share.meta.linkedin.icon"></i>
</button>

API

Name Value Description
[shareButton] null Button name, e.g. 'facebook', 'twitter' ...etc.
[sbUrl] current URL Sharing link.
[sbTitle] null Override title meta tag for LinkedIn and Reddit.
[sbDescription] null Override description meta tag for LinkedIn, WhatsApp, Telegram and Pinterest
[sbImage] null Override image meta tag for Pinterest only.
[sbTags] null Override tags for Tumblr and Twitter.
(sbOpened) button name Stream that emits when share window has opened.
(sbClosed) button name Stream that emits when share dialog has closed.
(sbCount) share count Stream that emits share count of the share URL.

Share button component

Add a single share button

<share-button button="facebook"></share-button>
<share-button button="twitter" showName="true">Tweet!</share-button>
<share-button button="facebook" showName="true" showCount="true"><b>Share on Facebook</b></share-button>
<share-button button="pinterest" showName="true"></share-button>

API

Name Value Description
[button] null Button name, e.g. 'facebook', 'twitter' ...etc.
[theme] null Set button theme.
[size] 0 Button size, e.g. -4, 2.5, 1...etc.
[url] current URL Sharing link.
[title] null Override title meta tag for LinkedIn and Reddit.
[description] null Override description meta tag for LinkedIn, WhatsApp, Telegram and Pinterest
[image] null Override image meta tag for Pinterest only.
[tags] null Override tags for Tumblr and Twitter.
[showIcon] true Show button icon.
[showName] false Show button text.
[showCount] false Show share count.
(opened) button name Stream that emits when share window has opened.
(closed) button name Stream that emits when share dialog has closed.
(count) share count Stream that emits share count of the share URL.

Share buttons component

Add a collection of share buttons

<share-buttons></share-buttons>

API

Name Value Description
[include] [all buttons] Include certain buttons. Button's order will be as you type it.
[exclude] [ ] Exclude certain buttons.
[show] null Number of buttons to show, if defined 'more' button will appear.
[theme] null Set button theme.
[size] 0 Button size, e.g. -4, 2.5, 1...etc.
[url] current URL Sharing link.
[title] null Override title meta tag for LinkedIn and Reddit.
[description] null Override description meta tag for LinkedIn, WhatsApp, Telegram and Pinterest
[image] null Override image meta tag for Pinterest only.
[tags] null Override tags for Tumblr and Twitter.
[showIcon] true Show button icon.
[showName] false Show button text.
[showCount] false Show share count.
(opened) button name Stream that emits when share window has opened.
(closed) button name Stream that emits when share dialog has closed.
(count) share count Stream that emits share count of the share URL.

Global options

To use custom options globally, pass your options in forRoot(option) where the module is imported.

import { ShareButtonsModule, ShareButtonsOptions } from 'ngx-sharebuttons';

const options: ShareButtonsOptions = {
  include: ['facebook', 'twitter', 'google'],
  exclude: ['tumblr', 'stumble', 'vk'],
  theme: 'modern-light',
  gaTracking: true,
  twitterAccount: 'twitterUsername'
}

@NgModule({
  imports: [
    ShareButtonsModule.forRoot(options)
  ]
})
Option Value Description
include [all buttons] Include certain buttons. Button's order will be as you type it.
exclude [ ] Exclude certain buttons.
size 0 Buttons default size.
theme null Button theme name.
dialogWidth 500 Share popup window width.
dialogHeight 400 Share popup window height.
title null Override title meta tag (if button supports it).
description null Override description meta tag (if button supports it).
image null Override image meta tag. (if button supports it).
tags null Override tags meta tag for Tumblr and Twitter.
gaTracking false Roll sharing stats automatically into your Google Analytics.
twitterAccount null Add via @accountName at the end of the tweets.

Button Configuration

You can change the buttons meta data such as button icon and text

import { ShareButtonsModule } from 'ngx-sharebuttons';

const buttonsConfig = {
  facebook: {
    icon: 'fa fa-facebook-official',
    text: 'Share on Facebook'
  },
  twitter: {
    icon: 'fa fa-twitter-square',
    text: 'Tweet'
  },
  // and so on...
};

@NgModule({
  imports: [
    ShareButtonsModule.forRoot(options, buttonsConfig)
  ]
})

Styling guide

This is useful to customize the style for <share-button> and <share-buttons> components

@import '~ngx-sharebuttons/styles/variables';

// change buttons colors

$sb-buttons: (
  facebook: #488aff,
  twitter: #32db64,
  google: #f53d3d,
  stumble: #f4f4f4,
  linkedin: $sb-linkedin,
  pinterest: $sb-pinterest,
  reddit: $sb-reddit,
  tumblr: $sb-tumblr,
  whatsapp: $sb-whatsapp,
  telegram: $sb-telegram,
  email: $sb-email,
  vk: $sb-vk,
  more: $sb-more,
  copy: $sb-copy,
  print: $sb-print
);

// change other variables

$sb-border-radius: 10px;

@import '~ngx-sharebuttons/styles/share-buttons';

See all available variables

Custom theme

To create a custom theme, use the following classes:

.sb-custom-theme {

  &.sb-group {
    /** ... share buttons container */
  }
  .sb-wrapper { /** ... share button wrapper */
    .sb-inner { /** ... inner wrapper */
      .sb-content { /** ... content wrapper */
        .sb-icon { /** ... icon wrapper */ }
        .sb-text { /** ... text wrapper */ }
       }
      .sb-template { /** ... template wrapper */ }
      .sb-count { /** ... count wrapper */ }
    }

    // For conditional styles
    &.sb-show-icon.sb-show-text.sb-show-count {
      /** ... Apply when icon, text and count are shown */
      .sb-icon { /** ... icon wrapper */ }
      .sb-text { /** ... text wrapper */ }
    }
  }
}

Issues

If you identify any errors in this component, or have an idea for an improvement, please open an issue. I am excited to see what the community thinks of this project, and I would love your input!

Support

npm

License

Author

Murhaf Sousli

More plugins from the author