Social Sharing Plugin: Extensive Guide

The Social Sharing plugin, tailored for Publii CMS, empowers websites with extensive social media integration. It supports a vast array of 39 different platforms and enhances content visibility and user engagement through customizable and visually appealing social sharing buttons. With Platform-Colored options, you can effortlessly match your button colors to various social media platforms without requiring manual color adjustments.

Installation and Compatibility

To utilize the Social Sharing plugin, ensure your Publii CMS is updated to version 0.43.1 or higher. This plugin is tailored for compatibility with the latest Publii theme versions, particularly those released around October/November 2023.

To add support for the Social Sharing plugin to your older or custom Publii themes, follow these steps:

Locate the Relevant File: Open your file explorer and navigate to the Documents/Publii/sites/YOUR_SITE/input/themes/YOUR_THEME directory, where YOUR_SITE is the name of your site, and YOUR_THEME is the folder for the theme you are currently using.
Edit the post.hbs File: Use your preferred code editor to open the post.hbs file located in your theme's folder.
Insert the Social Sharing Code:
1. Find an appropriate place in the post.hbs file where you want the social sharing buttons to appear. It's typically placed near the bottom of the post template and looks like this: {{> share-buttons}}
2. Replace the above code with the custom social sharing code snippet: {{{@customSocialSharing}}}.
For instance, your code might look something like this:
```
{{#if @config.post.displayShareButtons}}
  {{#checkIfAll @plugins.socialSharing @plugins.socialSharing.state}}
    <div class="post__share">
        {{{@customSocialSharing}}}
    </div>
  {{/checkIfAll}}          
{{/if}}
```

General Settings

Button Display Modes

Icon Only: Displays only the social platform icon, providing a clean and minimalistic look. Ideal for websites with a modern, uncluttered design.
Text Only: Shows only the name of the social platform. This mode benefits users who prefer text labels for clarity and accessibility.
Icon and Text: Combines both the icon and the text label, offering a comprehensive view that is both visually appealing and informative.

Layout Options

Horizontal Layout: Aligns buttons in a linear row. Suitable for headers, footers, or any horizontal space in your website's layout.
Vertical Layout: Stacks buttons in a column, ideal for sidebars or narrow vertical spaces like popups.

Button Types

Link Buttons: Styled as text links with icons, these buttons offer a simple and minimalistic approach. The text and icon color can be adjusted to match your site's theme.
Outlined Buttons: These buttons feature a distinct border, providing an elegant and defined appearance. The border color can be customized to align with your site's design or represent the social platform's color scheme.
Solid Buttons: Solid buttons offer a bold, filled color, drawing more attention. They include a 'Luminance Adjust on Hover' feature, allowing the button to slightly change color when hovered over, enhancing the interactive experience.

Color Customization

Platform-Colored: These options dynamically adapt the color scheme of the buttons based on the selected social media platform, ensuring visual harmony and brand consistency. They allow you to configure colors for both the default and hover states, depending on your preferences and the design of your site.

Depending on the type of button you choose (link, outlined, or solid), you will have the flexibility to customize various elements of the buttons with color options specific to each platform:

Link Buttons:

Text: Choose to colorize the text of the link buttons.
Icon: Opt for coloring the icons within the link buttons.
Both Icon and Text: Apply colorization to the text and icons within link buttons.

Outlined Buttons:

Border: If you're using outlined buttons, you can select this option to colorize the border.
Text and Icons: This option lets you colorize the text and icons for outlined buttons.
Border, Text, and Icons: This comprehensive option allows you to colorize the border, text, and icons for outlined buttons.

Solid Buttons:

Background: You can also colorize the solid buttons' backgrounds, providing further customization possibilities.

Platform-colored options simplify the process, ensuring your buttons seamlessly match the color schemes of social media platforms, resulting in a cohesive and visually appealing user experience tailored to your site's theme and the selected button type.

Social Platforms

In this section, you can select and configure various social media platforms for sharing content from your website. It allows for rearranging the order of social buttons using a drag-and-drop method and renaming the buttons. For example, you can rename a button from "Facebook" to "Share with Facebook" for more precise user guidance.

This section not only allows for the selection of social media sharing buttons but also provides several additional options that are essential for specific platforms.

Facebook App ID: Enter your Facebook App ID here. This ID is essential for enabling features like sharing via Facebook Messenger.
Twitter Handle: Define your Twitter account's handle. This handle is appended when sharing content via Twitter, for example, 'via @TwitterHandle'. If left blank, the author's Twitter handle is used.
Clipboard Alert Text: Customize the alert text when a URL is copied to the clipboard. The default text is "URL copied to clipboard".
Mastodon Domain Label: Customize the label text for the Mastodon domain input field. This label appears as a prompt when users are asked to enter their Mastodon domain.

Styling Options

Text Color: Allows customization of the text color on buttons, ensuring alignment with your website's color scheme.
Text Color on Hover: Defines the text color when the mouse hovers over the button.
Icon Color: Customizes the color of icons within the button. This setting is available when specific button styles and platform color conditions are met.
Icon Color on Hover: Changes the icon color on mouse hover, enhancing user interaction.
Border Text Color: Alters the text color for buttons with borders. This option comes into play based on the button style and specific platform-colored border conditions.
Background Color: Sets the background color of buttons, allowing for a harmonious integration with the site's design. It is dependent on the button style and platform background color settings.
Luminance Adjustment: Modifies the luminance of the social platform's background color on hover, offering a customizable visual effect. This feature allows for lightening or darkening the button color in the hover state, providing dynamic visual feedback to the users.
Border Width: Allows setting the border width for buttons, providing a way to adjust button aesthetics based on design requirements.
Button Hover Effect: Select the hover effect for buttons. Available options include: None, Translate Up, Scale, Rotate, Skew, Scale and Translate, Translate XY, Rotate and Scale, and Custom. This feature enhances the interactive experience by allowing diverse animations and transformations on hover.
Button Padding: Adjusts the padding around buttons, ensuring comfortable spacing and alignment with the overall design.
Button Border Radius: Defines the border radius for buttons, allowing for rounded or sharp edges based on stylistic preferences.
Font Family: Choose the font family for button text, ensuring typographic consistency with your site's design. This option supports official Publii theme fonts and allows for custom font specifications. It's compatible with the theme's CSS font variables, making it easy to align with the overall design aesthetics of your website.
Font Size: Adjusts the font size for button text, aligning it with your website's typography for a cohesive look.

Advanced Customization

Container CSS Class: Define a custom CSS class for the container. The default value is "scl-container". This option allows for advanced styling and layout control.
Button CSS Class: Set a specific CSS class for buttons. The default value is "scl-btn". Helpful in applying custom styles and behaviors to buttons.
Theme's Popup Container CSS Class: Specify the CSS class name for the theme's popup container, with the default value being js-post__share-popup. Keep this default class unless you use a custom popup to display social media buttons with your class name. The default class name is integral for official Publii themes, where social media buttons are displayed in a popup activated by a "Share" button. Only change this class if you use your popup implementation with a different class name, as this is crucial for ensuring the plugin functions correctly in such customized setups.
Social Sharing Popup: Toggle to enable or disable a popup window for social sharing buttons. This feature enhances user interaction by providing a dedicated sharing interface.
Popup Width: Define the width of the popup in pixels. This setting is active only when the social sharing popup is enabled.
Popup Height: Set the height of the popup in pixels. This configuration is applicable when the social sharing popup feature is active.

Optimized Performance: Intelligent Icon Mapping and Selective CSS Loading

By employing optimized SVG icons, the Social Sharing plugin guarantees a swift, visually appealing display with minimal impact on load times. A key feature is intelligent icon mapping, which dynamically generates a map of icons based on the specific social platforms chosen by the user. This approach ensures that only selected icons are loaded, avoiding the redundancy of unused graphics.

Furthermore, the plugin's smart CSS generation contributes significantly to performance efficiency. It customizes the CSS based on the button type, attaching only the needed CSS styles. For instance, in the case of a 'link' type button, which lacks borders or backgrounds, the plugin does not load styles related to these elements.

This meticulous attention to detail in code management means that the plugin enhances the user interface and maintains a lightweight presence on the host website, ensuring optimal page performance.

HTML Output and Accessibility

The plugin excels in performance and demonstrates a commitment to accessibility. This is evident in the dynamically generated HTML code it produces, which includes specific ARIA (Accessible Rich Internet Applications) attributes tailored to the type of buttons.

For example, depending on the chosen display option ('Icon only', 'Text only', or 'Both'), the plugin attaches the necessary ARIA attributes to enhance accessibility. This approach is particularly beneficial for screen readers and assistive technologies, ensuring that all users can interact with the social sharing buttons effectively regardless of their abilities.

Below is a sample of the HTML code generated by the plugin for three different platforms, showcasing how it adapts to various scenarios while prioritizing accessibility and performance.

<!-- Example of generated HTML for three platforms -->
<div class="scl-container">
    <!-- Diaspora Button -->
    <a href="https://share.diasporafoundation.org/..." class="scl-btn p-diaspora" aria-label="Diaspora">
        <svg width="24" height="24" aria-hidden="true" ...></svg>
        <span>Diaspora</span>
    </a>
    <!-- Digg Button -->
    <a href="https://digg.com/submit?url=..." class="scl-btn p-digg" aria-label="Digg">
        <svg width="40" height="24" aria-hidden="true" ...></svg>
        <span>Digg</span>
    </a>
    <!-- Email Button -->
    <a href="mailto:?subject=..." class="scl-btn p-email" aria-label="Email">
        <svg width="24" height="24" aria-hidden="true" ...></svg>
        <span>Email</span>
    </a>
</div>

Customization with CSS Variables

While the plugin offers extensive styling options through its user interface, it allows advanced users to directly manipulate styles using CSS variables. These variables are dynamically generated and can be adjusted to tailor the appearance of the sharing buttons to fit the specific needs of a website.

Below is a list of CSS variables available for customization, categorized by different button styles: 'Links', 'Outlined buttons', and 'Solid buttons'. Each category includes variables for colors, hover states, icon colors, borders, and more, allowing for detailed and precise styling.

/* Links */

  --scl-link-color: Color of the link text;
  --scl-link-color-hover: Hover color of the link text;
  --scl-link-icon-color: Color of the link icon;
  --scl-link-icon-color-hover: Hover color of the link icon;


/* Outlined buttons */

  --scl-outlined-color: Text color for outlined button;
  --scl-outlined-color-hover: Hover text color for outlined button;
  --scl-outlined-icon-color: Icon color for outlined button;
  --scl-outlined-icon-color-hover: Hover icon color for outlined button;
  --scl-outlined-border-color: Border color for outlined button;
  --scl-outlined-border-color-hover: Hover border color for outlined button;
  --scl-outlined-border-width: Border width for outlined button;
  --scl-btn-padding: Padding for button;


/* Solid buttons */

  --scl-btn-bg: Background color of the button;
  --scl-btn-bg-hover: Hover background color of the button;
  --scl-btn-txticon-color: Text and icon color for button with background;
  --scl-btn-txticon-color-hover: Hover text and icon color for button with background;
  --scl-btn-padding: Padding for button with background;
  --scl-hsla-luminance: Luminance adjustment for button with background;


/* General Variables */

  --scl-container-gap: Gap between container elements;
  --scl-container-direction: Layout direction of the container (row/column);
  --scl-btn-hover-effect: Hover effect for buttons;
  --scl-btn-gap: Gap between buttons;
  --scl-btn-transition: Transition effect for buttons;
  --scl-btn-border-radius: Border radius for buttons;
  --scl-btn-font-family: Font family for buttons;
  --scl-btn-font-size: Font size for buttons;
  --scl-icon-size: Size of the icon;

These variables provide a high degree of customization, empowering users to fine-tune the aesthetic aspects of the social sharing buttons to integrate with their website design seamlessly.