Documentation Project

https://verbb.io/craft-plugins/social-share/docs
Admin
This project appears to be a documentation repository, providing guides and information across...
Tokens:19,134
Snippets:213
Trust Score:8
Update:4 months ago
Show doc for...
Tokens:
Raw
### Install Social Share via Composer

Source: https://verbb.io/craft-plugins/social-share/docs/get-started/installation-setup

Use Composer to add the Social Share package to your project and then install it within Craft.

```bash
cd /path/to/project
```

```bash
composer require verbb/social-share && php craft plugin/install social-share
```

--------------------------------

### Get All Providers

Source: https://verbb.io/craft-plugins/social-share/docs/v2/heading-template-guides/available-variables

Returns a collection of all available Provider objects.

```APIDOC
## `craft.socialShare.getProviders()`

### Description
Returns a collection of all Provider objects.

### Method
`getProviders()`

### Parameters
None

### Response
#### Success Response
- A collection of Provider objects.
```

--------------------------------

### Provider-Specific Configuration

Source: https://verbb.io/craft-plugins/social-share/docs/get-started/configuration

Configure settings for individual social media providers, such as Facebook. This example shows how to set the `appId` and `appSecret` for Facebook.

```php
return [
    '*' => [
        // ...
        'providers' => [
            'facebook' => [
                'appId' => '••••••••••••••••••••••••••••',
                'appSecret' => '••••••••••••••••••••••••••••',
            ],
        ],
    ],
];

```

--------------------------------

### Get Button

Source: https://verbb.io/craft-plugins/social-share/docs/v2/heading-template-guides

Retrieves a generic Button object for a given provider.

```APIDOC
## `craft.socialShare.getButton(handle, options)`

### Description
Returns a Button for a given provider.

### Method
Twig Function

### Endpoint
N/A

### Parameters
#### Path Parameters
- **handle** (string) - Required - The handle of the provider.
- **options** (object) - Optional - Additional options for configuring the button.

### Request Example
```twig
{{ craft.socialShare.getButton('twitter', { text: 'Share' }) }}
```

### Response
#### Success Response
- `button` (object) - The Button object.

#### Response Example
```json
{
  "example": "{Button Object}"
}
```
```

--------------------------------

### MyProvider Class Implementation

Source: https://verbb.io/craft-plugins/social-share/docs/developers/custom-provider

Define your custom provider class extending the base `Provider` class. Implement required methods such as `getPrimaryColor()` and `getIcon()`. This example provides a basic structure.

```php
<?php
namespace modules\sitemodule;

class MyProvider extends Provider
{
    // Properties
    // =========================================================================

    public static string $handle = 'myProvider';


    // Public Methods
    // =========================================================================

    public function getPrimaryColor(): ?string
    {
        return '#000000';
    }

    public function getIcon(): ?string
    {
        return '<svg ...';
    }
}
```

--------------------------------

### Get Share Button

Source: https://verbb.io/craft-plugins/social-share/docs/v2/heading-template-guides

Retrieves a Share Button object for a given provider.

```APIDOC
## `craft.socialShare.getShareButton(handle, options)`

### Description
Returns a Share Button for a given provider.

### Method
Twig Function

### Endpoint
N/A

### Parameters
#### Path Parameters
- **handle** (string) - Required - The handle of the provider.
- **options** (object) - Optional - Additional options for configuring the button.

### Request Example
```twig
{{ craft.socialShare.getShareButton('twitter', { url: 'https://craftcms.com' }) }}
```

### Response
#### Success Response
- `button` (object) - The Share Button object.

#### Response Example
```json
{
  "example": "{Share Button Object}"
}
```
```

--------------------------------

### Customizing Button Size and Icon Size

Source: https://verbb.io/craft-plugins/social-share/docs/template-guides/rendering-buttons

This example demonstrates how to set a large overall button size while keeping the internal icon size small by directly manipulating CSS variables. Useful for creating visually distinct button elements.

```twig
{{ craft.socialShare.renderButton('facebook', {
    url: '...',
    buttonAttributes: {
        style: {
            '--size': '100px',
            '--icon-size': '20px',
        },
    },
    theme: true,
}) }}
```

--------------------------------

### Get Button Object

Source: https://verbb.io/craft-plugins/social-share/docs/v2/heading-template-guides/available-variables

Retrieves a generic Button object for a given provider.

```APIDOC
## `craft.socialShare.getButton(handle, options)`

### Description
Returns a Button for a given provider.

### Method
`getButton(handle, options)`

### Parameters
#### Path Parameters
- **handle** (string) - Required - The handle of the provider.
- **options** (object) - Optional - Additional options for the button.

### Response
#### Success Response
- A Button object.
```

--------------------------------

### Manually Render a Share Button

Source: https://verbb.io/craft-plugins/social-share/docs/feature-tour/share-buttons

Manually construct a share button using provider data. This example uses the `tag()` Twig function for cleaner HTML generation and includes attributes for opening a popup window.

```twig
{% set button = craft.socialShare.getShareButton('facebook') %}

{{ tag('a', {
    html: button.icon,
    href: 'javascript:void();',
    onclick: 'window.open(this.dataset.url, "ss_share_dialog", "width=626,height=436");',
    class: ['social-btn', button.handle],
    title: button.name,
    data: {
        url: button.providerUrl,
    },
    style: {
        color: button.primaryColor,
    },
}) }}
```

--------------------------------

### Get Share Button Object

Source: https://verbb.io/craft-plugins/social-share/docs/v2/heading-template-guides/available-variables

Retrieves a Share Button object for a given provider.

```APIDOC
## `craft.socialShare.getShareButton(handle, options)`

### Description
Returns a Share Button for a given provider.

### Method
`getShareButton(handle, options)`

### Parameters
#### Path Parameters
- **handle** (string) - Required - The handle of the provider.
- **options** (object) - Optional - Additional options for the share button.

### Response
#### Success Response
- A Share Button object.
```

--------------------------------

### Get All Share Count Providers

Source: https://verbb.io/craft-plugins/social-share/docs/feature-tour/share-counts

Fetches all providers that support share counts. This returns a collection of Provider objects.

```twig
{% for provider in craft.socialShare.getSharesCountProviders() %}
    {{ provider.name }}
{% endfor %}
```

--------------------------------

### Get Provider by Handle

Source: https://verbb.io/craft-plugins/social-share/docs/v2/heading-template-guides/available-variables

Retrieves a specific Provider object based on its handle.

```APIDOC
## `craft.socialShare.getProvider(handle)`

### Description
Returns a Provider for the provided handle.

### Method
`getProvider(handle)`

### Parameters
#### Path Parameters
- **handle** (string) - Required - The unique handle of the provider.

### Response
#### Success Response
- A Provider object matching the handle.
```

--------------------------------

### Get All Providers

Source: https://verbb.io/craft-plugins/social-share/docs/v2/heading-template-guides

Retrieves a collection of all available Provider objects from the Social Share plugin.

```APIDOC
## `craft.socialShare.getProviders()`

### Description
Returns a collection of all Provider objects.

### Method
Twig Function

### Endpoint
N/A

### Parameters
None

### Request Example
```twig
{{ craft.socialShare.getProviders() }}
```

### Response
#### Success Response
- `collection` (object) - A collection of Provider objects.

#### Response Example
```json
{
  "example": "[Collection of Provider Objects]"
}
```
```

--------------------------------

### Get Share Button Providers

Source: https://verbb.io/craft-plugins/social-share/docs/feature-tour/share-buttons

Fetch all available providers that support share buttons. This returns a collection of Provider objects.

```twig
{% for provider in craft.socialShare.getShareButtonProviders() %}
    {{ provider.name }}
{% endfor %}
```

--------------------------------

### Get Shares Count

Source: https://verbb.io/craft-plugins/social-share/docs/v2/heading-template-guides

Retrieves the number of shares for a given URL and provider.

```APIDOC
## `craft.socialShare.getShares(handle, url, options)`

### Description
Returns a the number of shares for a given provider and url.

### Method
Twig Function

### Endpoint
N/A

### Parameters
#### Path Parameters
- **handle** (string) - Required - The handle of the provider.
- **url** (string) - Required - The URL to get the share count for.
- **options** (object) - Optional - Additional options for the request.

### Request Example
```twig
{{ craft.socialShare.getShares('facebook', 'https://craftcms.com') }}
```

### Response
#### Success Response
- `count` (integer) - The number of shares.

#### Response Example
```json
{
  "example": 6789
}
```
```

--------------------------------

### Get Providers with Follower Counts

Source: https://verbb.io/craft-plugins/social-share/docs/v2/heading-template-guides/available-variables

Returns a collection of providers that support follower counts.

```APIDOC
## `craft.socialShare.getFollowersCountProviders()`

### Description
Returns a collection of all Provider objects that support Follower Counts.

### Method
`getFollowersCountProviders()`

### Parameters
None

### Response
#### Success Response
- A collection of Provider objects that support follower counts.
```

--------------------------------

### Get Providers for Share Buttons

Source: https://verbb.io/craft-plugins/social-share/docs/v2/heading-template-guides/available-variables

Returns a collection of providers that can be used to generate share buttons.

```APIDOC
## `craft.socialShare.getShareButtonProviders()`

### Description
Returns a collection of all Provider objects that support Share Buttons.

### Method
`getShareButtonProviders()`

### Parameters
None

### Response
#### Success Response
- A collection of Provider objects that support share buttons.
```

--------------------------------

### Get Provider by Handle

Source: https://verbb.io/craft-plugins/social-share/docs/v2/heading-template-guides

Retrieves a specific Provider object based on its unique handle.

```APIDOC
## `craft.socialShare.getProvider(handle)`

### Description
Returns a Provider for the provided handle.

### Method
Twig Function

### Endpoint
N/A

### Parameters
#### Path Parameters
- **handle** (string) - Required - The unique handle of the provider.

### Request Example
```twig
{{ craft.socialShare.getProvider('twitter') }}
```

### Response
#### Success Response
- `provider` (object) - The Provider object corresponding to the handle.

#### Response Example
```json
{
  "example": "{Twitter Provider Object}"
}
```
```

--------------------------------

### Get Providers Supporting Share Buttons

Source: https://verbb.io/craft-plugins/social-share/docs/v2/heading-template-guides

Retrieves a collection of Provider objects that support the rendering of share buttons.

```APIDOC
## `craft.socialShare.getShareButtonProviders()`

### Description
Returns a collection of all Provider objects that support Share Buttons.

### Method
Twig Function

### Endpoint
N/A

### Parameters
None

### Request Example
```twig
{{ craft.socialShare.getShareButtonProviders() }}
```

### Response
#### Success Response
- `collection` (object) - A collection of Provider objects supporting share buttons.

#### Response Example
```json
{
  "example": "[Collection of Share Button Provider Objects]"
}
```
```

--------------------------------

### Get All Providers

Source: https://verbb.io/craft-plugins/social-share/docs/template-guides/available-variables

Retrieves a collection of all available Provider objects. Useful for iterating through all supported social networks.

```twig
{{ craft.socialShare.getProviders() }}
```

--------------------------------

### Get Providers Supporting Follower Counts

Source: https://verbb.io/craft-plugins/social-share/docs/v2/heading-template-guides

Retrieves a collection of Provider objects that support follower count functionality.

```APIDOC
## `craft.socialShare.getFollowersCountProviders()`

### Description
Returns a collection of all Provider objects that support Follower Counts.

### Method
Twig Function

### Endpoint
N/A

### Parameters
None

### Request Example
```twig
{{ craft.socialShare.getFollowersCountProviders() }}
```

### Response
#### Success Response
- `collection` (object) - A collection of Provider objects supporting follower counts.

#### Response Example
```json
{
  "example": "[Collection of Follower Count Provider Objects]"
}
```
```

--------------------------------

### Get Providers with Share Counts

Source: https://verbb.io/craft-plugins/social-share/docs/v2/heading-template-guides/available-variables

Returns a collection of providers that support share counts.

```APIDOC
## `craft.socialShare.getSharesCountProviders()`

### Description
Returns a collection of all Provider objects that support Share Counts.

### Method
`getSharesCountProviders()`

### Parameters
None

### Response
#### Success Response
- A collection of Provider objects that support share counts.
```

--------------------------------

### Get Follower Count Providers

Source: https://verbb.io/craft-plugins/social-share/docs/feature-tour/follower-counts

Iterate over all providers that support fetching follower counts. This returns a collection of Provider objects.

```twig
{% for provider in craft.socialShare.getFollowerCountProviders() %}
    {{ provider.name }}
{% endfor %}
```

--------------------------------

### Get Share Button Object

Source: https://verbb.io/craft-plugins/social-share/docs/template-guides/available-variables

Returns a Share Button object for a specified provider. This object can be further manipulated or rendered.

```twig
{{ craft.socialShare.getShareButton('twitter') }}
```

--------------------------------

### GraphQL JSON Response for Social Share Buttons

Source: https://verbb.io/craft-plugins/social-share/docs/v2/heading-developers/graphql

This is an example of the JSON response structure when querying for social share button data. It shows the data for multiple buttons and the detailed information for a single button.

```json
{
    "data": {
        "socialShare": {
            "buttons": [
                {
                    "primaryColor": "#3b5997"
                },
                {
                    "primaryColor": "#1da1f2"
                }
            ],
            "button": {
                "name": "Facebook",
                "handle": "facebook",
                "primaryColor": "#3b5997",
                "icon": "<svg fill=\"currentColor\" viewBox=\"0 0 320 512\"><path d=\"M279.14 288l14.22-92.66h-88.91v-60.13c0-25.35 12.42-50.06 52.24-50.06h40.42V6.26S260.43 0 225.36 0c-73.22 0-121.08 44.38-121.08 124.72v70.62H22.89V288h81.39v224h100.17V288z\"></path></svg>",
            }
        }
    }
}
```

--------------------------------

### Get Providers Supporting Share Counts

Source: https://verbb.io/craft-plugins/social-share/docs/v2/heading-template-guides

Retrieves a collection of Provider objects that support share count functionality.

```APIDOC
## `craft.socialShare.getSharesCountProviders()`

### Description
Returns a collection of all Provider objects that support Share Counts.

### Method
Twig Function

### Endpoint
N/A

### Parameters
None

### Request Example
```twig
{{ craft.socialShare.getSharesCountProviders() }}
```

### Response
#### Success Response
- `collection` (object) - A collection of Provider objects supporting share counts.

#### Response Example
```json
{
  "example": "[Collection of Share Count Provider Objects]"
}
```
```

--------------------------------

### Get Follower Count

Source: https://verbb.io/craft-plugins/social-share/docs/v2/heading-template-guides/available-variables

Fetch the number of followers for a given provider and account identifier. Requires the provider handle and the account name/ID.

```twig
{{ craft.socialShare.getFollowers(handle, account, options) }}
```

--------------------------------

### Get Providers Supporting Share Buttons

Source: https://verbb.io/craft-plugins/social-share/docs/template-guides/available-variables

Retrieves a collection of Provider objects that can render share buttons. This is useful for dynamically generating UI elements for sharing content.

```twig
{{ craft.socialShare.getShareButtonProviders() }}
```

--------------------------------

### Query Share Counts

Source: https://verbb.io/craft-plugins/social-share/docs/v2/heading-developers/graphql

Use the `shares` query to get the share count for a specific URL and provider handle. The `handle` and `url` arguments are required. You can alias queries to retrieve multiple counts in one request.

```graphql
{
    socialShare {
        shares(handle: "facebook", url: "https://www.nytimes.com")
        twitterShares: shares(handle: "twitter", url: "https://www.nytimes.com")
    }
}
```

```json
{
    "data": {
        "socialShare": {
            "shares": "4.1M",
            "twitterShares": "5.7M"
        }
    }
}
```

--------------------------------

### Get Specific Provider by Handle

Source: https://verbb.io/craft-plugins/social-share/docs/template-guides/available-variables

Retrieves a single Provider object based on its unique handle. Use this when you need to access specific settings or methods for a known provider.

```twig
{{ craft.socialShare.getProvider('twitter') }}
```

--------------------------------

### Get Providers Supporting Follower Counts

Source: https://verbb.io/craft-plugins/social-share/docs/template-guides/available-variables

Retrieves a collection of Provider objects that specifically support fetching follower counts. Useful for filtering providers when only follower data is needed.

```twig
{{ craft.socialShare.getFollowersCountProviders() }}
```

--------------------------------

### Get Follower Count with Friendly Numbers Disabled

Source: https://verbb.io/craft-plugins/social-share/docs/feature-tour/follower-counts

Fetch follower counts and explicitly disable the 'friendly count' formatting, which converts raw numbers into abbreviated notations (e.g., '54.6K'). This displays the exact numerical value.

```twig
{{ craft.socialShare.getFollowers('facebook', 'craftcms', {
    friendlyCount: false,
})

{# Would render... #}
87372
```

--------------------------------

### Get Providers Supporting Share Counts

Source: https://verbb.io/craft-plugins/social-share/docs/template-guides/available-variables

Retrieves a collection of Provider objects that support fetching share counts. Use this when your application needs to display or process the number of times content has been shared.

```twig
{{ craft.socialShare.getSharesCountProviders() }}
```

--------------------------------

### Support Share Button

Source: https://verbb.io/craft-plugins/social-share/docs/developers/custom-provider

Configure your provider to support sharing content. Implement `supportsShareButton()` and the `getShareUrl()` method to generate the correct share URL.

```php
public static function supportsShareButton(): bool
{
    return true;
}

public function getShareUrl(string $url, ?string $text = null, array $params = []): ?string
{
    return UrlHelper::urlWithParams('https://my-provider.com/sharer.php', array_filter(array_merge([
        'url' => $url,
        'text' => $text,
    ], $params)));
}
```

--------------------------------

### Navigate to Craft Project Directory

Source: https://verbb.io/craft-plugins/social-share/docs/v2/heading-get-started/installation-setup

Use this command to change your current directory to your Craft project's root folder in the terminal.

```bash
cd /path/to/project
```

--------------------------------

### craft.socialShare.getProviders()

Source: https://verbb.io/craft-plugins/social-share/docs/template-guides/available-variables

Returns a collection of all available Provider objects.

```APIDOC
## `craft.socialShare.getProviders()`

### Description
Returns a collection of all Provider objects.

### Method
Twig Function

### Parameters
None

### Response
#### Success Response
- **providers** (Collection) - A collection of Provider objects.
```

--------------------------------

### Render Share Button

Source: https://verbb.io/craft-plugins/social-share/docs/v2/heading-template-guides

Renders a Share Button for a given provider, outputting the HTML.

```APIDOC
## `craft.socialShare.renderShareButton(handle, options)`

### Description
Returns a rendered Share Button for a given provider.

### Method
Twig Function

### Endpoint
N/A

### Parameters
#### Path Parameters
- **handle** (string) - Required - The handle of the provider.
- **options** (object) - Optional - Additional options for configuring the button.

### Request Example
```twig
{{ craft.socialShare.renderShareButton('facebook', { url: 'https://craftcms.com' }) }}
```

### Response
#### Success Response
- `html` (string) - The rendered HTML for the share button.

#### Response Example
```html
<a href="...">Share on Facebook</a>
```
```

--------------------------------

### craft.socialShare.getShareButtonProviders()

Source: https://verbb.io/craft-plugins/social-share/docs/template-guides/available-variables

Returns a collection of all Provider objects that support share buttons.

```APIDOC
## `craft.socialShare.getShareButtonProviders()`

### Description
Returns a collection of all Provider objects that support Share Buttons.

### Method
Twig Function

### Parameters
None

### Response
#### Success Response
- **providers** (Collection) - A collection of Provider objects that support share buttons.
```

--------------------------------

### Get Share Count

Source: https://verbb.io/craft-plugins/social-share/docs/v2/heading-template-guides/available-variables

Retrieves the share count for a given URL on a specified provider.

```APIDOC
## `craft.socialShare.getShares(handle, url, options)`

### Description
Returns the number of shares for a given provider and URL.

### Method
`getShares(handle, url, options)`

### Parameters
#### Path Parameters
- **handle** (string) - Required - The handle of the provider.
- **url** (string) - Required - The URL to get the share count for.
- **options** (object) - Optional - Additional options for the request.

### Response
#### Success Response
- The number of shares for the specified URL.
```

--------------------------------

### Render Button with Basic Theming

Source: https://verbb.io/craft-plugins/social-share/docs/template-guides/rendering-buttons

Enable basic theming for social share buttons by passing `theme: true`. This provides a minimally styled button, suitable for quick integration.

```twig
{{ craft.socialShare.renderButton('facebook', {
    url: '...',
    theme: true,
}) }}
```

--------------------------------

### Get Followers Count

Source: https://verbb.io/craft-plugins/social-share/docs/v2/heading-template-guides

Retrieves the number of followers for a given provider and account identifier.

```APIDOC
## `craft.socialShare.getFollowers(handle, account, options)`

### Description
Returns a the number of followers for a given provider and identifier (username, ID, etc).

### Method
Twig Function

### Endpoint
N/A

### Parameters
#### Path Parameters
- **handle** (string) - Required - The handle of the provider.
- **account** (string) - Required - The username or ID of the account.
- **options** (object) - Optional - Additional options for the request.

### Request Example
```twig
{{ craft.socialShare.getFollowers('twitter', 'craftcms') }}
```

### Response
#### Success Response
- `count` (integer) - The number of followers.

#### Response Example
```json
{
  "example": 12345
}
```
```

--------------------------------

### Support Followers Count

Source: https://verbb.io/craft-plugins/social-share/docs/developers/custom-provider

Implement follower count functionality for your provider. This involves setting `supportsFollowersCount()` to true and providing the `getFollowersCount()` method.

```php
public static function supportsFollowersCount(): bool
{
    return true;
}

public function getFollowersCount(string $account): ?int
{
    // Your logic to fetch the followers count
}
```

--------------------------------

### Render Button

Source: https://verbb.io/craft-plugins/social-share/docs/v2/heading-template-guides

Renders a generic Button for a given provider, outputting the HTML.

```APIDOC
## `craft.socialShare.renderButton(handle, options)`

### Description
Returns a rendered Button for a given provider.

### Method
Twig Function

### Endpoint
N/A

### Parameters
#### Path Parameters
- **handle** (string) - Required - The handle of the provider.
- **options** (object) - Optional - Additional options for configuring the button.

### Request Example
```twig
{{ craft.socialShare.renderButton('facebook', { text: 'Share' }) }}
```

### Response
#### Success Response
- `html` (string) - The rendered HTML for the button.

#### Response Example
```html
<button>Share on Facebook</button>
```
```

--------------------------------

### craft.socialShare.renderButton(handle, options)

Source: https://verbb.io/craft-plugins/social-share/docs/template-guides/available-variables

Renders a button for a given provider directly into HTML.

```APIDOC
## `craft.socialShare.renderButton(handle, options)`

### Description
Returns a rendered Button for a given provider.

### Method
Twig Function

### Parameters
#### Path Parameters
- **handle** (string) - Required - The handle of the social media provider.
- **options** (object) - Optional - Additional options for configuring the button.

### Response
#### Success Response
- **html** (string) - The rendered HTML for the button.
```

--------------------------------

### Get Follower Count

Source: https://verbb.io/craft-plugins/social-share/docs/v2/heading-template-guides/available-variables

Retrieves the follower count for a specified account on a given provider.

```APIDOC
## `craft.socialShare.getFollowers(handle, account, options)`

### Description
Returns the number of followers for a given provider and identifier (username, ID, etc).

### Method
`getFollowers(handle, account, options)`

### Parameters
#### Path Parameters
- **handle** (string) - Required - The handle of the provider.
- **account** (string) - Required - The account identifier (username, ID, etc.).
- **options** (object) - Optional - Additional options for the request.

### Response
#### Success Response
- The number of followers for the specified account.
```

--------------------------------

### Render Button

Source: https://verbb.io/craft-plugins/social-share/docs/v2/heading-template-guides/available-variables

Returns the HTML for a rendered generic Button for a given provider.

```APIDOC
## `craft.socialShare.renderButton(handle, options)`

### Description
Returns a rendered Button for a given provider.

### Method
`renderButton(handle, options)`

### Parameters
#### Path Parameters
- **handle** (string) - Required - The handle of the provider.
- **options** (object) - Optional - Additional options for rendering the button.

### Response
#### Success Response
- The HTML string for the rendered button.
```

--------------------------------

### Render Share Button

Source: https://verbb.io/craft-plugins/social-share/docs/v2/heading-template-guides/available-variables

Returns the HTML for a rendered Share Button for a given provider.

```APIDOC
## `craft.socialShare.renderShareButton(handle, options)`

### Description
Returns a rendered Share Button for a given provider.

### Method
`renderShareButton(handle, options)`

### Parameters
#### Path Parameters
- **handle** (string) - Required - The handle of the provider.
- **options** (object) - Optional - Additional options for rendering the share button.

### Response
#### Success Response
- The HTML string for the rendered share button.
```

--------------------------------

### craft.socialShare.getShareButton(handle, options)

Source: https://verbb.io/craft-plugins/social-share/docs/template-guides/available-variables

Generates a share button object for a given provider.

```APIDOC
## `craft.socialShare.getShareButton(handle, options)`

### Description
Returns a Share Button for a given provider.

### Method
Twig Function

### Parameters
#### Path Parameters
- **handle** (string) - Required - The handle of the social media provider.
- **options** (object) - Optional - Additional options for configuring the button.

### Response
#### Success Response
- **shareButton** (Object) - A Share Button object.
```

--------------------------------

### Support Share Count

Source: https://verbb.io/craft-plugins/social-share/docs/developers/custom-provider

Enable share count retrieval for your provider. Set `supportsSharesCount()` to true and implement the `getSharesCount()` method to return the share count for a given URL.

```php
public static function supportsSharesCount(): bool
{
    return true;
}

public function getSharesCount(string $url): ?int
{
    // Your logic to fetch the shares count
}
```

--------------------------------

### craft.socialShare.getProvider(handle)

Source: https://verbb.io/craft-plugins/social-share/docs/template-guides/available-variables

Returns a specific Provider object based on its handle.

```APIDOC
## `craft.socialShare.getProvider(handle)`

### Description
Returns a Provider for the provided handle.

### Method
Twig Function

### Parameters
#### Path Parameters
- **handle** (string) - Required - The unique handle of the provider.

### Response
#### Success Response
- **provider** (Object) - The Provider object matching the handle.
```

--------------------------------

### Default Social Share Configuration

Source: https://verbb.io/craft-plugins/social-share/docs/get-started/configuration

This snippet shows the default configuration options for the Social Share plugin. Add this to your `social-share.php` file if you need to override the default values.

```php
<?php

return [
    '*' => [
        'enableCache' => true,
        'cacheDuration' => 86400,
        'friendlyCount' => true,
        'minShareCount' => null,
        'useModalForShare' => true,
        'buttonAttributes' => [],
        'iconWrapperAttributes' => [],
        'labelAttributes' => [],
        'labelWrapperAttributes' => [],
        'contentAttributes' => [],
        'providers' => [],
    ]
];

```

--------------------------------

### craft.socialShare.renderShareButton(handle, options)

Source: https://verbb.io/craft-plugins/social-share/docs/template-guides/available-variables

Renders a share button for a given provider directly into HTML.

```APIDOC
## `craft.socialShare.renderShareButton(handle, options)`

### Description
Returns a rendered Share Button for a given provider.

### Method
Twig Function

### Parameters
#### Path Parameters
- **handle** (string) - Required - The handle of the social media provider.
- **options** (object) - Optional - Additional options for configuring the button.

### Response
#### Success Response
- **html** (string) - The rendered HTML for the share button.
```

--------------------------------

### Share Buttons

Source: https://verbb.io/craft-plugins/social-share/docs/developers/graphql

Query Share Button objects. You can also use the singular `shareButton` to fetch a single share button.

```APIDOC
## Share Buttons

### Description
Query Share Button objects. You can also use the singular `shareButton` to fetch a single share button.

### Query
`socialShare {
    shareButtons(handle: [String], url: String, text: String, params: [String]) {
        url
    }
    shareButton(handle: String!) {
        name
        handle
        primaryColor
        icon
        url
    }
}`

### Arguments
#### `shareButtons` Arguments
- **handle** ([String]) - Narrows the query results based on the button provider’s handle.
- **url** (String) - Provide the URL to be shared.
- **text** (String) - Provide the text to be shared.
- **params** ([String]) - Provide any other params to be included in the share URL.

#### `shareButton` Arguments
- **handle** (String!) - Narrows the query results based on the button provider’s handle.

### Example
```graphql
{
    socialShare {
        shareButtons(handle: ["facebook", "twitter"], url: "https://my-site.test") {
            url
        }

        shareButton(handle: "facebook") {
            name
            handle
            primaryColor
            icon
            url
        }
    }
}
```

### Response Example
```json
{
    "data": {
        "socialShare": {
            "shareButtons": [
                {
                    "url": "https://www.facebook.com/sharer/sharer.php?u=https%3A//my-site.test"
                },
                {
                    "url": "https://twitter.com/intent/tweet?url=https%3A//my-site.test"
                }
            ],
            "shareButton": {
                "name": "Facebook",
                "handle": "facebook",
                "primaryColor": "#3b5997",
                "icon": "<svg fill=\"currentColor\" viewBox=\"0 0 320 512\"><path d=\"M279.14 288l14.22-92.66h-88.91v-60.13c0-25.35 12.42-50.06 52.24-50.06h40.42V6.26S260.43 0 225.36 0c-73.22 0-121.08 44.38-121.08 124.72v70.62H22.89V288h81.39v224h100.17V288z\"></path></svg>",
                "url": "https://www.facebook.com/sharer/sharer.php?u=https%3A//my-site.test"
            }
        }
    }
}
```
```

--------------------------------

### Get Button Object

Source: https://verbb.io/craft-plugins/social-share/docs/template-guides/available-variables

Retrieves a generic Button object for a specified provider. This can be used for custom button implementations.

```twig
{{ craft.socialShare.getButton('twitter') }}
```

--------------------------------

### craft.socialShare.getButton(handle, options)

Source: https://verbb.io/craft-plugins/social-share/docs/template-guides/available-variables

Generates a button object for a given provider.

```APIDOC
## `craft.socialShare.getButton(handle, options)`

### Description
Returns a Button for a given provider.

### Method
Twig Function

### Parameters
#### Path Parameters
- **handle** (string) - Required - The handle of the social media provider.
- **options** (object) - Optional - Additional options for configuring the button.

### Response
#### Success Response
- **button** (Object) - A Button object.
```

--------------------------------

### Provider Methods

Source: https://verbb.io/craft-plugins/social-share/docs/developers/provider

The Provider object provides methods for generating share URLs, buttons, and rendered HTML.

```APIDOC
## Provider Methods

### Description
The Provider object provides methods for generating share URLs, buttons, and rendered HTML.

### Methods
- **getShareUrl(url, text, params)** - Returns the share URL unique to each provider.
- **getShareButton(options)** - Returns the Share Button.
- **renderShareButton(options)** - Returns the rendered HTML for the Share Button.
- **getButton(options)** - Returns the Button.
- **renderButton(options)** - Returns the rendered HTML for the Button.
```

--------------------------------

### Get Share Count

Source: https://verbb.io/craft-plugins/social-share/docs/template-guides/available-variables

Retrieves the number of shares for a given URL and provider. This method is essential for displaying social proof or tracking content virality.

```twig
{{ craft.socialShare.getShares('facebook', 'https://craftcms.com') }}
```

--------------------------------

### Render a Share Button with Custom Options

Source: https://verbb.io/craft-plugins/social-share/docs/feature-tour/share-buttons

Render a share button with additional parameters for the share URL, such as text and an image. Assumes an 'entry' variable is available.

```twig
{{ craft.socialShare.renderShareButton('facebook', {
    url: entry.url,
    text: entry.title,

    params: {
        image: entry.featuredImage.one.url,
    },
}) }}
```

--------------------------------

### Get Facebook Share Count for Current Page

Source: https://verbb.io/craft-plugins/social-share/docs/feature-tour/share-counts

Retrieves the total number of times the current page has been shared on Facebook. The current URL is used by default.

```twig
{{ craft.socialShare.getShares('facebook') }}
```

--------------------------------

### Get Facebook Share Count for a Specific URL

Source: https://verbb.io/craft-plugins/social-share/docs/feature-tour/share-counts

Fetches the share count for a specified URL from Facebook. This is useful when you need to check counts for a URL other than the current page.

```twig
{% set url = craft.app.request.absoluteUrl %}

{{ craft.socialShare.getShares('facebook', url) }}
```

--------------------------------

### Query Share Buttons

Source: https://verbb.io/craft-plugins/social-share/docs/v2/heading-developers/graphql

Fetch Share Button objects using the `shareButtons` query for multiple handles or the `shareButton` query for a single button. The `handle` and `url` arguments are important for `shareButtons`, while `shareButton` requires only the `handle`.

```graphql
{
    socialShare {
        shareButtons(handle: ["facebook", "twitter"], url: "https://my-site.test") {
            url
        }

        shareButton(handle: "facebook") {
            name
            handle
            primaryColor
            icon
            url
        }
    }
}
```

```json
{
    "data": {
        "socialShare": {
            "shareButtons": [
                {
                    "url": "https://www.facebook.com/sharer/sharer.php?u=https%3A//my-site.test"
                },
                {
                    "url": "https://twitter.com/intent/tweet?url=https%3A//my-site.test"
                }
            ],
            "shareButton": {
                "name": "Facebook",
                "handle": "facebook",
                "primaryColor": "#3b5997",
                "icon": "<svg fill=\"currentColor\" viewBox=\"0 0 320 512\"><path d=\"M279.14 288l14.22-92.66h-88.91v-60.13c0-25.35 12.42-50.06 52.24-50.06h40.42V6.26S260.43 0 225.36 0c-73.22 0-121.08 44.38-121.08 124.72v70.62H22.89V288h81.39v224h100.17V288z\"></path></svg>",
                "url": "https://www.facebook.com/sharer/sharer.php?u=https%3A//my-site.test"
            }
        }
    }
}
```

--------------------------------

### Provider Object

Source: https://verbb.io/craft-plugins/social-share/docs/v2/heading-developers/provider

Details the attributes and methods available for a Provider object.

```APIDOC
## Provider Object

### Description
Represents a social media provider with attributes like name, handle, primary color, and icon. It also provides methods to generate share URLs and buttons.

### Attributes

*   **name** (string) - The name of the provider.
*   **handle** (string) - The handle of the provider.
*   **primaryColor** (string) - The primary brand color of the provider.
*   **icon** (string) - The SVG icon of the provider.

### Methods

*   **getShareUrl(url, text, params)** (string) - Generates the share URL unique to each provider.
*   **getShareButton(options)** (object) - Returns the Share Button object.
*   **renderShareButton(options)** (string) - Returns the rendered HTML for the Share Button.
*   **getButton(options)** (object) - Returns the Button object.
*   **renderButton(options)** (string) - Returns the rendered HTML for the Button.
```

--------------------------------

### Manually Render a Social Media Button

Source: https://verbb.io/craft-plugins/social-share/docs/feature-tour/buttons

This snippet demonstrates how to manually construct a social media button using data provided by the plugin. It allows for full control over the HTML and attributes, using the `getButton` function to retrieve provider details like icon, handle, name, and color.

```twig
{% set button = craft.socialShare.getButton('facebook') %}

{{ tag('a', {
    html: button.icon,
    href: '...',
    class: ['social-btn', button.handle],
    title: button.name,
    style: {
        color: button.primaryColor,
    },
}) }}

{# Would render... #}
<a href="..." class="social-btn facebook" title="Facebook" style="color: #3b5997;"><svg ...</a>
```

--------------------------------

### Get Share Count for an Arbitrary URL

Source: https://verbb.io/craft-plugins/social-share/docs/feature-tour/share-counts

Fetches the share count for any given URL from Facebook, regardless of whether it is part of your website. This allows for flexible share count retrieval.

```twig
{{ craft.socialShare.getShares('facebook', 'https://verbb.io') }}
```

--------------------------------

### Follower Counts

Source: https://verbb.io/craft-plugins/social-share/docs/developers/graphql

Query for the Follower count of a provided account identifier and a provider handle. The `handle` and `account` arguments are required.

```APIDOC
## Follower Counts

### Description
Query for the Follower count of a provided account identifier and a provider handle.

### Query
`socialShare {
    followers(handle: String!, account: String!, friendlyCount: Boolean, enableCache: Boolean, cacheDuration: Int)
    twitterFollowers: followers(handle: String!, account: String!, friendlyCount: Boolean, enableCache: Boolean, cacheDuration: Int)
}`

### Arguments
#### `followers` Arguments
- **handle** (String!) - Narrows the query results based on the shares provider’s handle.
- **account** (String!) - Narrows the query results based on the account to check followers for.
- **friendlyCount** (Boolean) - Whether the returned count should be a "friendly" number.
- **enableCache** (Boolean) - Whether to enable the cache for results.
- **cacheDuration** (Int) - The number of seconds to cache results for.

### Example
```graphql
{
    socialShare {
        followers(handle: "facebook", account: "nytimes")
        twitterFollowers: followers(handle: "twitter", account: "nytimes")
    }
}
```

### Response Example
```json
{
    "data": {
        "socialShare": {
            "followers": "18M",
            "twitterFollowers": "54.7M"
        }
    }
}
```
```

--------------------------------

### Render Share Button

Source: https://verbb.io/craft-plugins/social-share/docs/v2/heading-template-guides/available-variables

Directly render a share button for a given provider. This is a convenient way to quickly add sharing functionality.

```twig
{{ craft.socialShare.renderShareButton(handle, options) }}
```

--------------------------------

### Get Facebook Share Count with Render Options

Source: https://verbb.io/craft-plugins/social-share/docs/feature-tour/share-counts

Retrieves the Facebook share count for a given URL while applying specific render options such as enabling cache and setting cache duration.

```twig
{{ craft.socialShare.getShares('facebook', entry.url, {
    enableCache: true,
    cacheDuration: 3600,
    friendlyCount: false,
}) }}
```

--------------------------------

### Share Counts

Source: https://verbb.io/craft-plugins/social-share/docs/developers/graphql

Query for the Share count of a provided URL and a provider handle. The `handle` and `url` arguments are required.

```APIDOC
## Share Counts

### Description
Query for the Share count of a provided URL and a provider handle.

### Query
`socialShare {
    shares(handle: String!, url: String!, friendlyCount: Boolean, enableCache: Boolean, cacheDuration: Int)
    twitterShares: shares(handle: String!, url: String!, friendlyCount: Boolean, enableCache: Boolean, cacheDuration: Int)
}`

### Arguments
#### `shares` Arguments
- **handle** (String!) - Narrows the query results based on the shares provider’s handle.
- **url** (String!) - Narrows the query results based on the URL to check shares for.
- **friendlyCount** (Boolean) - Whether the returned count should be a "friendly" number.
- **enableCache** (Boolean) - Whether to enable the cache for results.
- **cacheDuration** (Int) - The number of seconds to cache results for.

### Example
```graphql
{
    socialShare {
        shares(handle: "facebook", url: "https://www.nytimes.com")
        twitterShares: shares(handle: "twitter", url: "https://www.nytimes.com")
    }
}
```

### Response Example
```json
{
    "data": {
        "socialShare": {
            "shares": "4.1M",
            "twitterShares": "5.7M"
        }
    }
}
```
```

--------------------------------

### Get Share Count for an Entry URL

Source: https://verbb.io/craft-plugins/social-share/docs/feature-tour/share-counts

Retrieves the share count for a specific entry's URL from Facebook. This is commonly used when displaying share counts for blog posts or other entry types.

```twig
{{ craft.socialShare.getShares('facebook', entry.url) }}
```

--------------------------------

### craft.socialShare.getFollowersCountProviders()

Source: https://verbb.io/craft-plugins/social-share/docs/template-guides/available-variables

Returns a collection of all Provider objects that support follower counts.

```APIDOC
## `craft.socialShare.getFollowersCountProviders()`

### Description
Returns a collection of all Provider objects that support Follower Counts.

### Method
Twig Function

### Parameters
None

### Response
#### Success Response
- **providers** (Collection) - A collection of Provider objects that support follower counts.
```

--------------------------------

### Get Follower Count for a Specific User/Channel

Source: https://verbb.io/craft-plugins/social-share/docs/feature-tour/follower-counts

Fetch the follower count for a given social media platform and user identifier. The required identifier format varies by platform (e.g., username, channel ID).

```twig
{{ craft.socialShare.getFollowers('facebook', 'craftcms') }}
```

--------------------------------

### GraphQL Query for Social Share Buttons

Source: https://verbb.io/craft-plugins/social-share/docs/v2/heading-developers/graphql

Use this query to fetch multiple social share buttons by their handles and retrieve specific fields like `primaryColor`. It also demonstrates fetching a single button's details.

```graphql
{
    socialShare {
        buttons(handle: ["facebook", "twitter"]) {
            primaryColor
        }

        button(handle: "facebook") {
            name
            handle
            primaryColor
            icon
        }
    }
}
```

--------------------------------

### Get Facebook Share Count with Friendly Count Disabled

Source: https://verbb.io/craft-plugins/social-share/docs/feature-tour/share-counts

Fetches the Facebook share count for a URL and disables the 'friendly count' formatting, displaying the raw number instead. This is useful for precise data display.

```twig
{{ craft.socialShare.getShares('facebook', entry.url, {
    friendlyCount: false,
}) }}

{# Would render...
87372
#}
```

--------------------------------

### Register Custom Provider

Source: https://verbb.io/craft-plugins/social-share/docs/developers/custom-provider

Register your custom provider class with the Social Share plugin's provider system. This is typically done in your module's `init()` method or a similar initialization point.

```php
namespace modules\sitemodule;

use craft\events\RegisterComponentTypesEvent;
use modules\sitemodule\MyProvider;
use verbb\socialshare\services\Providers;
use yii\base\Event;

Event::on(Providers::class, Providers::EVENT_REGISTER_PROVIDER_TYPES, function(RegisterComponentTypesEvent $event) {
    $event->types[] = MyProvider::class;
});
```

--------------------------------

### Get Follower Count with Custom Options

Source: https://verbb.io/craft-plugins/social-share/docs/feature-tour/follower-counts

Retrieve follower counts while specifying custom options like enabling cache and setting the cache duration. This allows for fine-grained control over API calls and data freshness.

```twig
{{ craft.socialShare.getFollowers('facebook', 'craftcms', {
    enableCache: true,
    cacheDuration: 3600,
    friendlyCount: false,
}) }}
```
Tokens:
Raw