From b5834e89dc631609da46aef6678807ddb829c503 Mon Sep 17 00:00:00 2001
From: Adrien Dupuis <61695653+adriendupuis@users.noreply.github.com>
Date: Mon, 2 Feb 2026 14:44:12 +0100
Subject: [PATCH] page_blocks: Enhance "Exposing content relations from blocks"

---
 docs/content_management/pages/page_blocks.md | 61 +++++++++++++++++---
 1 file changed, 52 insertions(+), 9 deletions(-)

diff --git a/docs/content_management/pages/page_blocks.md b/docs/content_management/pages/page_blocks.md
index d265601a33..dbb70ff54a 100644
--- a/docs/content_management/pages/page_blocks.md
+++ b/docs/content_management/pages/page_blocks.md
@@ -113,15 +113,58 @@ You can use this parameter, for example, in block template:
 
 #### Exposing content relations from blocks
 
-Page blocks, for example Embed block or Collection block, can embed other content items.
-Publishing a page with such blocks creates Relations to those content items.
+Page blocks which embed other content items should expose those relations.
 
-When creating a custom block with embeds, you can ensure such Relations are created using the block Relation collection event.
-
-The event is dispatched on content publication.
-You can hook your event listener to the `BlockRelationEvents::getCollectBlockRelationsEventName` event.
-
-To expose relations, pass an array containing Content IDs to the `Ibexa\FieldTypePage\Event\CollectBlockRelationsEvent::setRelations()` method.
 If embedded Content changes, old Relations are removed automatically.
-
 Providing Relations also invalidates HTTP cache for your block response in one of the related content items changes.
+
+The following [block attribute types](page_block_attributes.md#block-attribute-types) create relations to content items (even when [nested](page_block_attributes.md#nested-attribute-configuration)):
+
+- `embed`
+- `embedvideo`
+- `locationlist`
+- `richtext`
+
+When creating a custom block embedding contents not through those types of attribute, you can ensure such relations are created using the block relation collection event.
+The event is dispatched on content publication and on content view.
+
+You can hook your event listener to the event name obtained with `BlockRelationEvents::getCollectBlockRelationsEventName($blockTypeIdentifier)`.
+To expose relations, pass an array of integers containing Content IDs to the `Ibexa\FieldTypePage\Event\CollectBlockRelationsEvent::setRelations()` method.
+
+```php
+<?php
+
+namespace App\EventSubscriber;
+
+use Ibexa\FieldTypePage\Event\BlockRelationEvents;
+use Ibexa\FieldTypePage\Event\CollectBlockRelationsEvent;
+use Ibexa\FieldTypePage\FieldType\Page\Block\Renderer\BlockRenderEvents;
+use Ibexa\FieldTypePage\FieldType\Page\Block\Renderer\Event\PreRenderEvent;
+use Symfony\Component\EventDispatcher\EventSubscriberInterface;
+
+final class MyBlockEventSubscriber implements EventSubscriberInterface
+{
+    public static function getSubscribedEvents(): array
+    {
+        return [
+            BlockRenderEvents::getBlockPreRenderEventName('my_block') => 'onBlockPreRender',
+            BlockRelationEvents::getCollectBlockRelationsEventName('my_block') => 'onCollectBlockRelationsEvent'
+        ];
+    }
+
+    public function onBlockPreRender(PreRenderEvent $event): void
+    {
+        // …
+    }
+
+    public function onCollectBlockRelationsEvent(CollectBlockRelationsEvent $event): void
+    {
+        // …
+        $event->setRelations([1, 2, 3]);
+    }
+}
+```
+
+When creating a custom block attribute type that embeds content items, you can also create relations with a service implementing
+`\Ibexa\FieldTypePage\FieldType\Page\Block\Relation\Extractor\BlockAttributeRelationExtractorInterface`
+and tagged `ibexa.field_type.page.relation.attribute.type.extractor`.