Facebook

Setting up the Facebook stream

1 / Create a Facebook app

Create a new app with the button “Create app” at the top right.

In the App details dialog, enter a suitable app name.

Under use cases, in the Content management area, select the use case “Manage everything on your Page” and click Next.

In the Business step, choose the option “I don’t want to connect a business portfolio yet” and click Next again.

Skip the following Requirements step without selecting anything (just click Next). An overview appears – use “Go to dashboard” to switch to the app dashboard.

In the left navigation bar, open Use cases and click “Customize”.

Scroll down, find the permissions pages_read_engagement and pages_read_user_content and enable them with “Add”. These permissions are required to generate an access token in the Contao back end later.

In the left navigation bar under “Facebook Login for Business”, open Settings. In the field “Valid OAuth Redirect URIs”, enter the following URL: https://your-domain.com/_facebook/auth (Replace the domain with the one of your own website.)

Under App settings → Basic you find the App ID and the App secret – you will need both in the Contao back end later. In this area you also have to enter the App domain (the domain of your own website). Without it, the access token cannot be generated and an error message appears.

To read posts you must be an admin of the page, otherwise you first have to submit the Facebook app for app review.

2 / Create a news archive

Create a new news archive in the Contao back end into which the Facebook posts will be imported. A redirect page must be selected, although it is not relevant for the Social Feed bundle.

3 / Create an account and generate an access token

Under the menu item Social Feed Accounts, use the button Create a new Social Feed account to create a new account. Select Facebook as the type.

• Facebook account: The name of the account as it appears in the URL
• App ID: You find the App ID in your app under App settings -> Basic.
• App secret: You find the App secret in your app under App settings -> Basic.
• Access token: The access token is filled in automatically.
• News archive: The archive into which the Facebook posts will be imported.
• Cron job execution: Choose between different intervals for importing posts.
• Import page posts only: If you select this option, only the page’s own posts are imported and no posts that users have written on its wall.
• Last import: These fields are filled in automatically. You can empty them so that the cron job runs again.

After you click the button “Generate access token”, you are redirected to Facebook to connect the app with your Facebook page.

Make sure you have entered and saved the account name, the App ID and the App secret first. Only then click the button.

After a successful connection, the access token is generated automatically and saved in the database.

In the first window, click Continue.

Then select the page whose posts you want to import.

Check the permissions. Click Save.

The user is now connected to the app. Click Got it and the access token is saved automatically.

You can test the generated access token with the Access Token Debugger. If you enter the token on that page and click Debug, it should look like the following screenshot. It is important that the expiry date is Never, otherwise you would have to generate a new access token after it expires.

It is also important that the user who generated the access token remains an admin of the Facebook page. Otherwise the access token becomes invalid. The access token also becomes invalid if the user changes their Facebook password.

4 / Create a module

The page Module setup contains everything else about creating and placing the module.

Twitter

Setting up the Twitter stream

1 / Create a Twitter developer account and app

To show Twitter posts on your website you need a Twitter account and a Twitter developer account. You find a step-by-step guide here: Setting up the developer account/Twitter app.

2 / Create a news archive

First create a news archive into which the Twitter posts will be imported. You have to specify a redirect page for the news archive because it is a mandatory field, although it is not relevant for the Social Feed bundle as there is no news detail page. Ideally, create a separate news archive for each Twitter account, so you can deselect individual accounts in the news list module later.

3 / Create an account

To create an account, click Create a new Social Feed account and select the type Twitter. A form opens where you enter all the required account data. After saving, it may take 2-3 minutes until all posts are imported.

• API key: Found in the app details in the tab “Keys and tokens”.
• API secret key: Found in the app details in the tab “Keys and tokens”.
• Access token: Found in the app details in the tab “Keys and tokens”.
• Access token secret: Found in the app details in the tab “Keys and tokens”.
• Twitter account: Enter the name of the Twitter account, without @.
• Search term: Instead of showing the posts of an account, you can also search for a specific term.
• Maximum number of posts: The maximum number of posts imported at once.
• News archive: Select the news archive into which the Twitter posts should be imported.
• Cron job execution: Choose how often the cron job runs to import new Twitter posts. The options are: no cron job, every minute, hourly, daily, weekly and monthly.
• Also import retweets: If you enable this checkbox, retweets are imported and shown as well.
• Also import replies: If you enable this checkbox, replies are imported and shown as well.
• Link hashtags and mentions: If you enable this checkbox, hashtags (e.g. #contao) and mentions (e.g. @pdirGmbH) are linked. For this, the template news_social_feed_extended must be selected in the news list module.
• Last import: The two text fields for the last import only show when the last import took place.

4 / Create a module

The page Module setup contains everything else about creating and placing the module.

Instagram

Setting up the Instagram stream

1 / Create a Facebook app

Create a new app with the button “Create app” at the top right.

In the App details dialog, enter a suitable app name.

Under Business messaging, select the use case “Manage messaging & content on Instagram”.

In the Business step, choose the option “I don’t want to connect a business portfolio yet” and click Next again.

Skip the following Requirements step without selecting anything (just click Next). An overview appears – use “Go to dashboard” to switch to the app dashboard.

In the left navigation bar, open Use cases and click “Customize”.

This area contains the Instagram app ID and the app secret. You will enter both values later in the corresponding Social Feed account in the Contao back end.

Scroll further down and click “Set up” at “4. Set up Instagram business login”.

A popup opens. Enter the redirect URL there: https://your-domain.com/_instagram/auth (Replace the domain with the one of your own website.)

At the bottom left of the menu, open App roles → Roles (1). Use the button “Add people” (2) to add a new role of type “Instagram tester” (3). In the search field, enter the name of the Instagram account whose content you want to read, select the correct account from the results and click “Add”.

Accept the invitation at the following link: https://www.instagram.com/accounts/manage_access

In the tab “Tester invites”, click “Accept”.

The Instagram tester should now be shown in the app roles – without the status “Pending”.

2 / Create a news archive

First create a new news archive. It collects your Instagram posts. When setting it up you have to specify a redirect page, although it plays no role for the Social Feed bundle. For a better overview, we recommend creating a separate archive for each Instagram account. That way you can easily hide individual accounts in the news list module later.

3 / Create an account and generate a token

Account settings

In the left navigation, go to PDIR APPS and click Social Feed accounts. Choose New account to create a new Social Feed account for the import.

Select Instagram as the type.

Paste the App ID and App secret into the corresponding fields, save, and use the button Request access token to generate a new access token. Before that, select the correct news archive into which the Instagram posts should be imported. You find the App ID and App secret in the Facebook app under API setup with Instagram business login.

Generate the access token

When you tick Request access token, you should be redirected to Instagram.

Log in with your Instagram credentials and confirm the access request with the button Allow.

The access token should now be generated and the fields Instagram access token and Access token expires on should be filled in.

Other fields

• Instagram account: Enter the profile name that should be shown on the website.
• Maximum number of posts: Defines how many posts are imported.
• News archive: Select the news archive into which the Instagram posts should be imported.
• Cron job execution: Choose how often the cron job runs to import new Instagram posts. The options are: no cron job, every minute, hourly, daily, weekly and monthly.
• Last import: The two text fields for the last import only show when the last import took place. Empty them to force a new import.
• Profile image: The profile image is not imported by default, so select it in this field to show it on the website. You can also set an image size, e.g. Important part, 50x50px.

4 / Create a module

The page Module setup contains everything else about creating and placing the module.

LinkedIn

Setting up the LinkedIn stream

1 / Create a LinkedIn developer account and app

To show LinkedIn posts on your website you need a LinkedIn account and a LinkedIn developer account. You find a step-by-step guide here: Setting up the LinkedIn app.

2 / Create a news archive

First create a news archive into which the LinkedIn posts will be imported. You have to specify a redirect page for the news archive because it is a mandatory field, although it is not relevant for the Social Feed bundle as there is no news detail page. Ideally, create a separate news archive for each LinkedIn account, so you can deselect individual accounts in the news list module later.

3 / Create an account

To create an account, click Create a new Social Feed account and select the type LinkedIn. A form opens where you enter all the required account data. After saving, it may take 2-3 minutes until all posts are imported.

• Client ID: Found in your LinkedIn app in the Auth tab.
• Client secret: Found in your LinkedIn app in the Auth tab.
• Company page ID: Shown in the URL of your company page (if you are an admin).
• Maximum number of posts: The maximum number of posts imported at once.
• News archive: Select the news archive into which the LinkedIn posts should be imported.
• Cron job execution: Choose how often the cron job runs to import new LinkedIn posts. The options are: no cron job, every minute, hourly, daily, weekly and monthly.
• Access token expires on: As long as the refresh token is valid, the access token is automatically extended by 2 months each time.
• Refresh token expires on: When the refresh token has expired, the access token has to be generated again manually.
• Last import: The two text fields for the last import only show when the last import took place.
• Profile image: The profile image is not imported by default, so select it in this field to show it on the website. You can also set an image size, e.g. Important part, 50x50px.

When you click the button “Generate access token”, you are redirected to LinkedIn to grant your app the required permissions.

Make sure you have entered and saved the client ID, the client secret and the company page ID first. Only then click the button.

After a successful authorization, the access token is saved automatically.

A refresh token is saved as well. It is used to regenerate the access token every 2 months. The refresh token is valid for one year. After that, the user has to generate the access token again with the checkbox ‘Generate access token’.

When the refresh token expires and the user has to act, the website admin receives a reminder email.

4 / Create a module

The page Module setup contains everything else about creating and placing the module.

Feed Moderation

Since version 2.5.0 you can choose which posts are imported and which are skipped. So far this feature is only available for Instagram; Facebook and Twitter will follow later.

First create a Social Feed account. You find all the information in the respective sections Facebook, Instagram or Twitter. The cron job should not be active, so that posts are not imported automatically.

Then select the news archive into which the posts should be imported (pencil icon). Click the button Social Feed at the top right, select your account and fetch the feed.

A list of posts appears, which you can select with checkboxes and import. After clicking the button Import entries (at the very bottom), the selected posts are imported into the news archive.

Module

1 / Create a module

Once you have created your accounts, create the corresponding module. Go to Themes > Front end modules of theme ID x (gear icon) and create a new module.

As module type, select Newslist under News. Select the news archives you want to show in your Social Feed stream. With the field Total number of items you can limit the number of posts. If you want a pagination, fill in the field Items per page.

As the news template, select news_social_feed. As the custom template, select mod_newslist_social_feed. Under image settings, adjust the image size as needed.

Under Social Feed settings you can set the maximum text length and the number of columns, enable/disable Masonry and show/hide images.

Extended template for Twitter

To link hashtags and mentions, select the news template news_social_feed_extended. In addition, the checkbox Link hashtags and mentions must be enabled in the Social Feed account.

You find a demo here: https://demo.pdir.de/social-feed-extended-template.

So far this only works for Twitter posts and not yet for Facebook and Instagram posts.

2 / Place the module

After creating the module, place it anywhere you like.

3 / Template adjustments

If you use Contao 4.4 or 4.5, the post image is not linked by default. If you want to link the image, adjust the template news_social_feed.html5 as follows.

<a href="<?= $this->url ?>" target="_blank">
    <?php if ($this->addImage && $this->sfImages): ?>
        <?php $this->insert('image', $this->arrData); ?>
    <?php endif; ?>
</a>

4 / Customize the stylesheets

You can change the path to the stylesheets in the template mod_newslist_social_feed. This requires at least version 2.5.2 of the Social Feed module.

<?php  $GLOBALS['TL_CSS']['social_feed'] = 'bundles/pdirsocialfeed/css/social_feed.scss||static'; ?>