README

TYPO3 extension that integrates Facebook Social Plugins as a content element with full configuration.

Requirements

TYPO3 14.3+
PHP 8.5+

Plugins

The extension provides one content element that supports four Facebook Social Plugins:

Share Button: Share any URL or the current page
Page Plugin: Embed a Facebook page with configurable tabs, dimensions and display options
Embedded Post: Embed a public Facebook post
Embedded Video / Live Video Player: Embed a Facebook video or live stream

Installation

Install via Composer:

composer require refresj/facebook-socialplugins

Add the Site Set to your site configuration (config/sites/<your-site>/config.yaml):

dependencies:
    - refresj/facebook-socialplugins

Or add it as a dependency of your own Site Set.

Usage

Create a new content element and select Facebook Social Plugin (group Refresj). Choose the plugin type and fill in the options below.

Plugin	Options
Share Button	URL to share (custom URL or current page), layout (`button_count`, `button`, `box_count`), size (`small`, `large`)
Page Plugin	Facebook page URL, tabs (timeline, events, messages), width (180-500 px), height (min. 70 px), hide cover photo, show friend photos, hide call-to-action button, small header, adapt to container width
Embedded Post	Facebook post URL, width (350-750 px, empty = fluid), show caption text
Embedded Video	Facebook video URL, width (min. 220 px), allow fullscreen, autoplay (muted, not on mobile), show caption text, show captions

All plugins have a Lazy loading option (enabled by default).

Only http and https URLs are accepted. A content element without a selected plugin, or without a valid URL, renders nothing and does not load the SDK.

Configuration

Settings are managed via Sites → Setup → Gear icon button (bottom right of your site) under the Facebook Social Plugins category.

Setting	Description	Default
`appId`	Facebook App ID - create one at developers.facebook.com	(empty)
`locale`	SDK locale, e.g. `nl_NL`, `en_US`, `de_DE`	`en_US`

These can also be set directly in TypoScript:

plugin.tx_facebooksocialplugins.settings {
    appId  = your-app-id
    locale = nl_NL
}

Facebook JavaScript SDK

The SDK is loaded automatically via TYPO3's AssetCollector. When multiple Facebook Social Plugin content elements are placed on the same page, the SDK is only loaded once.

The SDK version used is v27.0.

Content Security Policy

The extension extends the frontend Content Security Policy of TYPO3 (Configuration/ContentSecurityPolicies.php) with the sources the plugins need:

Directive	Sources
`script-src-elem`	`https://connect.facebook.net`
`connect-src`	`https://connect.facebook.net`
`frame-src`	`https://*.facebook.com`

These mutations apply to all frontend sites of the installation. Depending on the plugin and your own policy, additional sources may be required. The Content-Security-Policy backend module of TYPO3 lists recent violations and suggests resolutions.

If the site-specific config/sites/<your-site>/csp.yaml overrides one of these directives with mode: set, the sources of this extension are lost. Add them to your own configuration with mode: extend:

mutations:
    - mode: extend
      directive: "connect-src"
      sources:
          - "https://connect.facebook.net"

Privacy

Loading the Facebook SDK connects the visitor's browser to Facebook (connect.facebook.net), which can transfer personal data and set cookies. In the EU this generally requires prior consent of the visitor.

This extension does not include consent management. The Lazy loading option only postpones the rendering of the plugin, the SDK script itself is always loaded on pages that contain a plugin. Make sure the content element is only output after consent, for example by combining it with your own consent tool.

Languages

The backend labels are available in English and Dutch. Translation files are located in Resources/Private/Language/.

License

GPL-2.0-or-later

refresj / facebook-socialplugins

Package info

Security

Fund package maintenance!

Statistics