Skip to content

Commit ca3beef

Browse files
fritzmgfritzmg
authored
Update Contao News Facebook documentation (contao#1068)
1 parent 3ea91d5 commit ca3beef

File tree

3 files changed

+263
-4
lines changed

3 files changed

+263
-4
lines changed

‎docs/dev/framework/hooks.md

+2-2
Original file line numberDiff line numberDiff line change
@@ -63,7 +63,7 @@ Using attributes or annotations means it is only necessary to create one file fo
6363
way of automatically registering services under the `App\` namespace within the `src/` folder.
6464
{{% /notice %}}
6565

66-
{{< tabs groupId="serviceConfig" >}}
66+
{{< tabs groupId="registering-hooks" >}}
6767
{{% tab name="Attribute" %}}
6868
{{< version-tag "4.13" >}} Contao implements [PHP attributes](https://www.php.net/manual/en/language.attributes.overview.php) (available
6969
since **PHP 8**) with which you can tag your service to be registered as a hook.
@@ -185,7 +185,7 @@ tagged with `contao.hook` and no method name is given, the `__invoke` method wil
185185
be called automatically. This also means that you can define the service annotation
186186
on the class, instead of a method:
187187

188-
{{< tabs groupId="serviceConfig" >}}
188+
{{< tabs groupId="registering-hooks" >}}
189189
{{% tab name="Attribute" %}}
190190
```php
191191
// src/EventListener/ParseArticlesListener.php

‎docs/manual/extensions/news-facebook-sync.de.md

+131-1
Original file line numberDiff line numberDiff line change
@@ -236,9 +236,12 @@ für Nachrichtenarchive.
236236

237237
## Hooks
238238

239+
Die Extension stellt einige [Hooks][Hooks] zur Verfügung, welche das Verhalten beeinflussen können, wenn zu Facebook gepostet, oder
240+
ein Post von Facebook zu Contao geholt wird.
241+
239242
### `processFacebookPost`
240243

241-
Die Erweiterung prozessiert einen Facebook Post und versucht diesen zu einem passenden Contao Nachrichtenbeitrag
244+
Die Erweiterung prozessiert einen Facebook-Post und versucht diesen zu einem passenden Contao Nachrichtenbeitrag
242245
umzuwandeln. Dieser Prozess kann mit dem `processFacebookPost` selbst angepasst werden. Als Rückgabewert wird
243246
ein Array erwartet, mit den finalen Daten für den Datenbankeintrag eines Nachrichtenbeitrags. Wenn der Rückgabewert
244247
`false` ist, wird kein Nachrichtenbeitrag erzeugt.
@@ -255,17 +258,144 @@ Wenn ein Contao Nachrichtenbeitrag als Facebook Post vorbereitet wird, wird entw
255258
Nachricht angegebene Text verwendet. Falls aber automatisch dieser Text angepasst werden soll, kann dies mit dem
256259
`changeFacebookMessage` Hook gemacht werden. Als Rückgabewert wird der finale Text erwartet.
257260

261+
258262
#### Parameter
259263

260264
1. _string_ `$message` Die bereits vorgefertigte Nachricht.
261265
2. _object_ `$objArticle` Der originale Contao Nachrichtenbeitrag.
262266
3. _object_ `$objArchive` Das Newsarchiv Objekt.
263267

264268

269+
#### Beispiel
270+
271+
Das folgende Beispiel implementiert einen Hook, der die URL zum Nachrichtenbeitrag an den Text des Facebook-Posts anhängt:
272+
273+
{{< tabs groupId="registering-hooks" >}}
274+
{{% tab name="Attribute" %}}
275+
```php
276+
// src/EventListener/ChangeFacebookMessageListener.php
277+
namespace App\EventListener;
278+
279+
use Contao\CoreBundle\DependencyInjection\Attribute\AsHook;
280+
use Contao\News;
281+
use Contao\NewsArchiveModel;
282+
use Contao\NewsModel;
283+
284+
#[AsHook('changeFacebookMessage')]
285+
class ChangeFacebookMessageListener
286+
{
287+
public function __invoke(string $message, NewsModel $news, NewsArchiveModel $archive): string
288+
{
289+
// Append the URL to photo posts
290+
if ($news->addImage && $news->fbPostAsPhoto) {
291+
$message .= "\n\n".News::generateNewsUrl($news, false, true);
292+
}
293+
294+
return $message;
295+
}
296+
}
297+
```
298+
{{% /tab %}}
299+
300+
{{% tab name="Annotation" %}}
301+
```php
302+
// src/EventListener/ChangeFacebookMessageListener.php
303+
namespace App\EventListener;
304+
305+
use Contao\CoreBundle\ServiceAnnotation\Hook;
306+
use Contao\News;
307+
use Contao\NewsArchiveModel;
308+
use Contao\NewsModel;
309+
310+
/**
311+
* @Hook("changeFacebookMessage")
312+
*/
313+
class ChangeFacebookMessageListener
314+
{
315+
public function __invoke(string $message, NewsModel $news, NewsArchiveModel $archive): string
316+
{
317+
// Append the URL to photo posts
318+
if ($news->addImage && $news->fbPostAsPhoto) {
319+
$message .= "\n\n".News::generateNewsUrl($news, false, true);
320+
}
321+
322+
return $message;
323+
}
324+
}
325+
```
326+
{{% /tab %}}
327+
{{% tab name="YAML" %}}
328+
```yaml
329+
# config/services.yaml
330+
services:
331+
App\EventListener\ActivateAccountListener:
332+
tags:
333+
- { name: contao.hook, hook: changeFacebookMessage }
334+
```
335+
```php
336+
// src/EventListener/ChangeFacebookMessageListener.php
337+
namespace App\EventListener;
338+
339+
use Contao\CoreBundle\ServiceAnnotation\Hook;
340+
use Contao\News;
341+
use Contao\NewsArchiveModel;
342+
use Contao\NewsModel;
343+
344+
class ChangeFacebookMessageListener
345+
{
346+
public function __invoke(string $message, NewsModel $news, NewsArchiveModel $archive): string
347+
{
348+
// Append the URL to photo posts
349+
if ($news->addImage && $news->fbPostAsPhoto) {
350+
$message .= "\n\n".News::generateNewsUrl($news, false, true);
351+
}
352+
353+
return $message;
354+
}
355+
}
356+
```
357+
{{% /tab %}}
358+
359+
{{% tab name="config.php" %}}
360+
```php
361+
// contao/config.php
362+
use App\EventListener\ChangeFacebookMessageListener;
363+
364+
$GLOBALS['TL_HOOKS']['changeFacebookMessage'][] = [ChangeFacebookMessageListener::class, '__invoke'];
365+
```
366+
```php
367+
// src/EventListener/ChangeFacebookMessageListener.php
368+
namespace App\EventListener;
369+
370+
use Contao\CoreBundle\ServiceAnnotation\Hook;
371+
use Contao\News;
372+
use Contao\NewsArchiveModel;
373+
use Contao\NewsModel;
374+
375+
class ChangeFacebookMessageListener
376+
{
377+
public function __invoke(string $message, NewsModel $news, NewsArchiveModel $archive): string
378+
{
379+
// Append the URL to photo posts
380+
if ($news->addImage && $news->fbPostAsPhoto) {
381+
$message .= "\n\n".News::generateNewsUrl($news, false, true);
382+
}
383+
384+
return $message;
385+
}
386+
}
387+
```
388+
{{% /tab %}}
389+
{{< /tabs >}}
390+
391+
265392
## Template Daten
266393

267394
In den Nachrichtentemplates stehen zusätzliche Daten zur Verfügung:
268395

269396
- _object_ `fbData` Die originalen Daten des Posts von Facebook.
270397
- _string_ `fbPostId` Die Facebook ID des verknüpften Facebook Posts.
271398
- _char_ `fromFb` Gibt an, ob der Nachrichtenbeitrag ursprünglich von Facebook importiert wurde.
399+
400+
401+
[Hooks]: /dev/framework/hooks/

‎docs/manual/extensions/news-facebook-sync.en.md

+130-1
Original file line numberDiff line numberDiff line change
@@ -220,6 +220,8 @@ There is a button to trigger a sync in the back end, within the global operation
220220

221221
## Hooks
222222

223+
The extension provides some [Hooks][Hooks] which allow you to alter the behavior when posting to Facebook or fetching Facebook posts.
224+
223225
### `processFacebookPost`
224226

225227
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.
@@ -232,7 +234,8 @@ The extension processes a Facebook post and tries to convert it to a fitting Con
232234

233235
### `changeFacebookMessage`
234236

235-
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.
237+
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.
238+
236239

237240
#### Parameters
238241

@@ -241,10 +244,136 @@ When posting a Contao news entry as a Facebook post, the extension either uses t
241244
3. _object_ `$objArchive` The news archive object.
242245

243246

247+
#### Example
248+
249+
The following example appends the news article's URL to any photo post:
250+
251+
{{< tabs groupId="registering-hooks" >}}
252+
{{% tab name="Attribute" %}}
253+
```php
254+
// src/EventListener/ChangeFacebookMessageListener.php
255+
namespace App\EventListener;
256+
257+
use Contao\CoreBundle\DependencyInjection\Attribute\AsHook;
258+
use Contao\News;
259+
use Contao\NewsArchiveModel;
260+
use Contao\NewsModel;
261+
262+
#[AsHook('changeFacebookMessage')]
263+
class ChangeFacebookMessageListener
264+
{
265+
public function __invoke(string $message, NewsModel $news, NewsArchiveModel $archive): string
266+
{
267+
// Append the URL to photo posts
268+
if ($news->addImage && $news->fbPostAsPhoto) {
269+
$message .= "\n\n".News::generateNewsUrl($news, false, true);
270+
}
271+
272+
return $message;
273+
}
274+
}
275+
```
276+
{{% /tab %}}
277+
278+
{{% tab name="Annotation" %}}
279+
```php
280+
// src/EventListener/ChangeFacebookMessageListener.php
281+
namespace App\EventListener;
282+
283+
use Contao\CoreBundle\ServiceAnnotation\Hook;
284+
use Contao\News;
285+
use Contao\NewsArchiveModel;
286+
use Contao\NewsModel;
287+
288+
/**
289+
* @Hook("changeFacebookMessage")
290+
*/
291+
class ChangeFacebookMessageListener
292+
{
293+
public function __invoke(string $message, NewsModel $news, NewsArchiveModel $archive): string
294+
{
295+
// Append the URL to photo posts
296+
if ($news->addImage && $news->fbPostAsPhoto) {
297+
$message .= "\n\n".News::generateNewsUrl($news, false, true);
298+
}
299+
300+
return $message;
301+
}
302+
}
303+
```
304+
{{% /tab %}}
305+
{{% tab name="YAML" %}}
306+
```yaml
307+
# config/services.yaml
308+
services:
309+
App\EventListener\ActivateAccountListener:
310+
tags:
311+
- { name: contao.hook, hook: changeFacebookMessage }
312+
```
313+
```php
314+
// src/EventListener/ChangeFacebookMessageListener.php
315+
namespace App\EventListener;
316+
317+
use Contao\CoreBundle\ServiceAnnotation\Hook;
318+
use Contao\News;
319+
use Contao\NewsArchiveModel;
320+
use Contao\NewsModel;
321+
322+
class ChangeFacebookMessageListener
323+
{
324+
public function __invoke(string $message, NewsModel $news, NewsArchiveModel $archive): string
325+
{
326+
// Append the URL to photo posts
327+
if ($news->addImage && $news->fbPostAsPhoto) {
328+
$message .= "\n\n".News::generateNewsUrl($news, false, true);
329+
}
330+
331+
return $message;
332+
}
333+
}
334+
```
335+
{{% /tab %}}
336+
337+
{{% tab name="config.php" %}}
338+
```php
339+
// contao/config.php
340+
use App\EventListener\ChangeFacebookMessageListener;
341+
342+
$GLOBALS['TL_HOOKS']['changeFacebookMessage'][] = [ChangeFacebookMessageListener::class, '__invoke'];
343+
```
344+
```php
345+
// src/EventListener/ChangeFacebookMessageListener.php
346+
namespace App\EventListener;
347+
348+
use Contao\CoreBundle\ServiceAnnotation\Hook;
349+
use Contao\News;
350+
use Contao\NewsArchiveModel;
351+
use Contao\NewsModel;
352+
353+
class ChangeFacebookMessageListener
354+
{
355+
public function __invoke(string $message, NewsModel $news, NewsArchiveModel $archive): string
356+
{
357+
// Append the URL to photo posts
358+
if ($news->addImage && $news->fbPostAsPhoto) {
359+
$message .= "\n\n".News::generateNewsUrl($news, false, true);
360+
}
361+
362+
return $message;
363+
}
364+
}
365+
```
366+
{{% /tab %}}
367+
{{< /tabs >}}
368+
369+
244370
## Template data
245371

246372
There is additional data available in the news templates:
247373

248374
- _object_ `fbData` The original Facebook post data
249375
- _string_ `fbPostId` The Facebook post ID of the linked Facebook post
250376
- _char_ `fromFb` Indicates whether this news entry was fetched from Facebook
377+
378+
379+
[Hooks]: /dev/framework/hooks/

0 commit comments

Comments
 (0)