Contao News Facebook Sync

inspiredminds/contao-news-facebook

by inspiredminds

Project web site: Contao News Facebook Sync

This extension allows to automatically import Facebook page (or group) posts as news entries. It also enables you to automatically post news entries on a Facebook page. This allows you to keep a Facebook page in sync with a news archive.

Installation

To install this extension, the composer.json of your Contao installation has to be modified first. Two adjustments have to be done: adding the private repository & adding the dependency.

To add the repository, add the following to your composer.json:

{
    "repositories": [
        {
            "type": "composer",
            "url": "https://token:<YOUR_TOKEN>@packdis.inspiredminds.at/r"
        }
    ]
}

Replace <YOUR_TOKEN> with the repository token you received from inspiredminds.

To add the dependency, add the following to your composer.json:

{
    "require": {
        "inspiredminds/contao-news-facebook": "^7.0"
    }
}
View a full example

After making this adjustment, run a composer update on the command line or update your packages via the Contao Manager. Then open the Contao Install Tool to update the database as usual.

Configuration

To configure this extension, a “Facebook App” needs to created first prior to version 7.0 of this extension. The details of this app are then needed for the configuration in the back end.

Creating a Facebook App

Starting with version 7.0 of the extension this step can be skipped.

  1. First you need to go to developers.facebook.com. If you do not have a Facebook developer account yet, you need to create one (or unlock your existing Facebook user as a developer account).
  2. Under My Apps click on Create App.
  3. Type in a Display Name for the App (e.g. the title of your website) and enter a contact email address.
  4. On the next page, you can add Products to your App. Add the Facebook Login by clicking on Set Up.
  5. On the next page, choose Web, then enter the URL of your website (including https://). Click on Save.
  6. On the left, click on Facebook Login » Settings. Under Valid OAuth Redirect URIs enter the following URL: https://example.org/system/modules/news_facebook/public/callback.php. Replace example.org with the domain of your website. Then click on Save Changes.
  7. On the left, click on Settings » Basic and enter your website’s domain unter App Domains. Then click on Save Changes.

The account under which you create this App must also have the rights to create timeline posts on the Facebook page you wish to synchronize with (optional if you only want to fetch Facebook Page posts). Alternatively you can also add further Administrator or Developers after you created the App in the Roles section.

Configure the App ID and App Secret in Contao

Starting with version 7.0 of the extension this step can be skipped.

In Contao, go to System - Settings, scroll down to the Facebook App section, enter the App ID and App Secret of your Facebook App. You can find this information in your Facebook App under Settings » Basic.

Facebook App settings

Configure the Contao News Archive

Go to the settings of your news archive. In the Facebook sync section enable Facebook sync and enter the numeric ID of the Facebook Page you want to synchronize with. If you wish to automatically fetch the Facebook Page posts and add them to your news archive, enable the Fetch page posts option. Optionally, also define a Page post date limit.

You can also do the same for a Facebook Group, if you want to fetch posts from that group. Note, however, that publishing news entries as Facebook posts is only supported for Facebook Pages, not for Groups.

Lastly you need to fetch an Access Token. Click on the Facebook connect button next to the input field - this will log you into Facebook and it will request some permissions from your Facebook user. After you have confirmed the permissions a “Long Term Access Token” will be fetched from Facebook.

If you want to let Contao publish news posts to your Facebook page, you need to allow the Facebook App to post publicly on your behalf, when granting permissions. The Facebook account under which you log in to fetch the Access Token also must have the rights to create timeline posts on the Facebook page.

News archive settings

Any downloaded images will be saved to the folder configured in your news archive (files/facebook_images by default). Like any other folder, this folder needs to be made public under Contao 4!

Additional settings

Since version 3.0.0 you can also set the following settings in the system settings of Contao under Facebook Sync:

No meta tags: since version 3.0.0 the extension also automatically includes an og:image meta tag in the <head> wherever a news article is parsed, so that its teaser image will be displayed by Facebook automatically, whenever someone shares a link to a news entry. With this option you can disable this functionality.

Post as photo: since version 3.0.0 news entries are not posted as photo posts anymore, whenever the news entry has a teaser image. With this option you can re-enable this functionality.

Back end settings

If you do not use a hook, the default headline length can be configured via

$GLOBALS['FACEBOOK_TITLE_LENGTH'] = …;

in your own config.php.

Usage

Fetch Facebook Page/Group posts

Once you have configured the news archive and also enabled the Fetch page posts or Fetch group posts option the extension will check for new Facebook posts hourly via Contao’s cronjob.

Publish Facebook posts

Contao news entries will be published as Facebook page posts under two conditions:

  • in the news entry’s properties, under the Facebook sync section, the Post to Facebook page option must be enabled
  • the news entry must be published

You can also define a custom message for the Facebook post. If no such message is defined, the news entry’s teaser is used by default.

The extension will check for new news entries to be published minutely via Contao’s cronjob.

News settings

Manual sync trigger

There is a button to trigger a sync in the back end, within the global operations for news archives.

News global operations

Hooks

The extension provides some Hooks which allow you to alter the behavior when posting to Facebook or fetching Facebook posts.

processFacebookPost

The extension processes a Facebook post and tries to convert it to a fitting Contao news entry as best as it can. If you want to customize the final data for a news entry of a Facebook post, you can use the processFacebookPost hook. It expects an array containing the final news entry data as the return value. If the return value equals to false, no news entry will be created.

Parameters

  1. array $arrData The already processed data which will be used for the new news entry.
  2. object $objPost The original Facebook post data.
  3. object $objArchive The news archive object.

changeFacebookMessage

When posting a Contao news entry as a Facebook post, the extension either uses the teaser or the specified message of the news entry. If you want to automatically provide a different message, you can use the changeFacebookMessage hook. It expects the final message as the return value.

Parameters

  1. string $message The already prepared message.
  2. object $objArticle The original Contao news entry.
  3. object $objArchive The news archive object.

Example

The following example appends the news article’s URL to any photo post:

// src/EventListener/ChangeFacebookMessageListener.php
namespace App\EventListener;

use Contao\CoreBundle\DependencyInjection\Attribute\AsHook;
use Contao\News;
use Contao\NewsArchiveModel;
use Contao\NewsModel;

#[AsHook('changeFacebookMessage')]
class ChangeFacebookMessageListener
{
    public function __invoke(string $message, NewsModel $news, NewsArchiveModel $archive): string
    {
        // Append the URL to photo posts
        if ($news->addImage && $news->fbPostAsPhoto) {
            $message .= "\n\n".News::generateNewsUrl($news, false, true);
        }

        return $message;
    }
}

// src/EventListener/ChangeFacebookMessageListener.php
namespace App\EventListener;

use Contao\CoreBundle\DependencyInjection\Attribute\AsHook;
use Contao\News;
use Contao\NewsArchiveModel;
use Contao\NewsModel;

#[AsHook('changeFacebookMessage')]
class ChangeFacebookMessageListener
{
    public function __invoke(string $message, NewsModel $news, NewsArchiveModel $archive): string
    {
        // Append the URL to photo posts
        if ($news->addImage && $news->fbPostAsPhoto) {
            $message .= "\n\n".News::generateNewsUrl($news, false, true);
        }

        return $message;
    }
}

# config/services.yaml
services:
    App\EventListener\ActivateAccountListener:
        tags:
            - { name: contao.hook, hook: changeFacebookMessage }

// src/EventListener/ChangeFacebookMessageListener.php
namespace App\EventListener;

use Contao\CoreBundle\ServiceAnnotation\Hook;
use Contao\News;
use Contao\NewsArchiveModel;
use Contao\NewsModel;

class ChangeFacebookMessageListener
{
    public function __invoke(string $message, NewsModel $news, NewsArchiveModel $archive): string
    {
        // Append the URL to photo posts
        if ($news->addImage && $news->fbPostAsPhoto) {
            $message .= "\n\n".News::generateNewsUrl($news, false, true);
        }

        return $message;
    }
}

// contao/config.php
use App\EventListener\ChangeFacebookMessageListener;

$GLOBALS['TL_HOOKS']['changeFacebookMessage'][] = [ChangeFacebookMessageListener::class, '__invoke'];

// src/EventListener/ChangeFacebookMessageListener.php
namespace App\EventListener;

use Contao\CoreBundle\ServiceAnnotation\Hook;
use Contao\News;
use Contao\NewsArchiveModel;
use Contao\NewsModel;

class ChangeFacebookMessageListener
{
    public function __invoke(string $message, NewsModel $news, NewsArchiveModel $archive): string
    {
        // Append the URL to photo posts
        if ($news->addImage && $news->fbPostAsPhoto) {
            $message .= "\n\n".News::generateNewsUrl($news, false, true);
        }

        return $message;
    }
}

Template data

There is additional data available in the news templates:

  • object fbData The original Facebook post data
  • string fbPostId The Facebook post ID of the linked Facebook post
  • char fromFb Indicates whether this news entry was fetched from Facebook