From c58dab598b40467eafcd2a41c8503e5d1fa6edde Mon Sep 17 00:00:00 2001 From: Adrien Dupuis <61695653+adriendupuis@users.noreply.github.com> Date: Mon, 2 Feb 2026 16:05:15 +0100 Subject: [PATCH 01/18] About `cacheable_query_params` --- .../field_types/field_type_reference/pagefield.md | 7 +++++-- docs/content_management/pages/page_blocks.md | 15 ++++++++------- 2 files changed, 13 insertions(+), 9 deletions(-) diff --git a/docs/content_management/field_types/field_type_reference/pagefield.md b/docs/content_management/field_types/field_type_reference/pagefield.md index d5b0977f76..042a5979a2 100644 --- a/docs/content_management/field_types/field_type_reference/pagefield.md +++ b/docs/content_management/field_types/field_type_reference/pagefield.md @@ -52,6 +52,9 @@ The `renderAction` has the following parameters: | `versionNo` | Version number of the content item to render. | | `languageCode` | Language code of the content item to render. | +Use `ibexa_append_cacheable_query_params(block)` as the third parameter of the [`controller()` Twig function]([[= symfony_doc =]]/reference/twig_reference.html#controller) +so if the block type has a `cacheable_query_params` configuration, it will be passed for its cache to vary on those query parameters. + Example usage: ``` html+twig @@ -60,7 +63,7 @@ Example usage: 'blockId': block.id, 'versionNo': versionInfo.versionNo, 'languageCode': field.languageCode -})) }} +}, ibexa_append_cacheable_query_params(block))) }} ``` As a whole a sample layout could look as follows: @@ -82,7 +85,7 @@ As a whole a sample layout could look as follows: 'blockId': block.id, 'versionNo': versionInfo.versionNo, 'languageCode': field.languageCode - })) }} + }, ibexa_append_cacheable_query_params(block))) }} {% endfor %} {% endif %} diff --git a/docs/content_management/pages/page_blocks.md b/docs/content_management/pages/page_blocks.md index d265601a33..f5f7533d70 100644 --- a/docs/content_management/pages/page_blocks.md +++ b/docs/content_management/pages/page_blocks.md @@ -18,15 +18,16 @@ For information on how to create and configure new layouts for the Page, see [Pa Each configured block has an identifier and the following settings: -| Setting | Description | -|--------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------| -| `name` | Name of the block used in the Page Builder interface. Translatable using the `ibexa_page_fieldtype` translation domain. | -| `category` | Category in the Page Builder **Page blocks** toolbox that the block is shown in. Translatable using the `ibexa_page_fieldtype` translation domain. | +| Setting | Description | +|--------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `name` | Name of the block used in the Page Builder interface. Translatable using the `ibexa_page_fieldtype` translation domain. | +| `category` | Category in the Page Builder **Page blocks** toolbox that the block is shown in. Translatable using the `ibexa_page_fieldtype` translation domain. | | `thumbnail` | Thumbnail used in the Page Builder **Page blocks** toolbox. | -| `views` | Available [templates for the block](#block-templates). | +| `views` | Available [templates for the block](#block-templates). | | `visible` | (Optional) Toggles the block's visibility in the Page Builder **Page blocks** toolbox. Remove the block from the layout before you publish another version of the page. | -| `configuration_template` | (Optional) Template for the block settings modal. | -| `attributes` | (Optional) List of [block attributes](page_block_attributes.md). | +| `configuration_template` | (Optional) Template for the block settings modal. | +| `attributes` | (Optional) List of [block attributes](page_block_attributes.md). | +| `cacheable_query_params` | (Optional) List of query parameters the block varies on. For example, if the block is paginated using `?page=ℕ` in the whole page URL, add `page` to this list. | For example: From d921f920804329d28ae82aa6c3393437d78dc857 Mon Sep 17 00:00:00 2001 From: Adrien Dupuis <61695653+adriendupuis@users.noreply.github.com> Date: Mon, 2 Feb 2026 17:04:45 +0100 Subject: [PATCH 02/18] About `cacheable_query_params` --- .../page_twig_functions.md | 32 +++++++++++++++++++ .../twig_function_reference.md | 1 + 2 files changed, 33 insertions(+) create mode 100644 docs/templating/twig_function_reference/page_twig_functions.md diff --git a/docs/templating/twig_function_reference/page_twig_functions.md b/docs/templating/twig_function_reference/page_twig_functions.md new file mode 100644 index 0000000000..b9263e0a0f --- /dev/null +++ b/docs/templating/twig_function_reference/page_twig_functions.md @@ -0,0 +1,32 @@ +--- +description: Page field and page block Twig functions access to configuration. +page_type: reference +edition: experience +month_change: true +--- + +# Page Twig functions + +## `ibexa_append_cacheable_query_params()` + +Get the query parameters of a page block as [configured in `cacheable_query_params`](page_blocks.md#block-configuration). + +```twig +{{ render_esi(controller('Ibexa\\Bundle\\FieldTypePage\\Controller\\BlockController::renderAction', { + 'locationId': locationId, + 'blockId': block.id, + 'versionNo': versionInfo.versionNo, + 'languageCode': field.languageCode +}, ibexa_append_cacheable_query_params(block))) }} +``` + +## `ibexa_page_layout()` + +Get the layout template of a landing page. + +```twig +{% include ibexa_page_layout(page) with {'zones': page.zones} %} +``` + +It can be used to render a [page field](pagefield.md). +For an example, you can look at how the default `vendor/ibexa/fieldtype-page/src/bundle/Resources/views/fields/ibexa_landing_page.html.twig` uses it. diff --git a/docs/templating/twig_function_reference/twig_function_reference.md b/docs/templating/twig_function_reference/twig_function_reference.md index abba7c79b3..c9810c8e80 100644 --- a/docs/templating/twig_function_reference/twig_function_reference.md +++ b/docs/templating/twig_function_reference/twig_function_reference.md @@ -14,6 +14,7 @@ In addition to the [native functions provided by Twig](https://twig.symfony.com/ "templating/twig_function_reference/content_twig_functions", "templating/twig_function_reference/component_twig_functions", "templating/twig_function_reference/field_twig_functions", + "templating/twig_function_reference/page_twig_functions", "templating/twig_function_reference/product_twig_functions", "templating/twig_function_reference/site_context_twig_functions", "templating/twig_function_reference/storefront_twig_functions", From d31ea55f5c4c030be75c252fe2aa87052055d59c Mon Sep 17 00:00:00 2001 From: Adrien Dupuis <61695653+adriendupuis@users.noreply.github.com> Date: Mon, 2 Feb 2026 17:25:43 +0100 Subject: [PATCH 03/18] mkdocs.yml + page_twig_functions.md --- mkdocs.yml | 1 + 1 file changed, 1 insertion(+) diff --git a/mkdocs.yml b/mkdocs.yml index 77a37fda43..0bec2ac49d 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -311,6 +311,7 @@ nav: - Content Twig functions: templating/twig_function_reference/content_twig_functions.md - Date Twig filters: templating/twig_function_reference/date_twig_filters.md - Field Twig functions: templating/twig_function_reference/field_twig_functions.md + - Page Twig functions: templating/twig_function_reference/page_twig_functions.md - Icon Twig functions: templating/twig_function_reference/icon_twig_functions.md - Image Twig functions: templating/twig_function_reference/image_twig_functions.md - Product Twig functions: templating/twig_function_reference/product_twig_functions.md From a5a41fa613a555d58d1447f9bea02a5bbd3a5e23 Mon Sep 17 00:00:00 2001 From: Adrien Dupuis <61695653+adriendupuis@users.noreply.github.com> Date: Mon, 2 Feb 2026 17:53:38 +0100 Subject: [PATCH 04/18] Update docs/content_management/field_types/field_type_reference/pagefield.md --- .../field_types/field_type_reference/pagefield.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/content_management/field_types/field_type_reference/pagefield.md b/docs/content_management/field_types/field_type_reference/pagefield.md index 042a5979a2..d725dd2ad3 100644 --- a/docs/content_management/field_types/field_type_reference/pagefield.md +++ b/docs/content_management/field_types/field_type_reference/pagefield.md @@ -53,7 +53,7 @@ The `renderAction` has the following parameters: | `languageCode` | Language code of the content item to render. | Use `ibexa_append_cacheable_query_params(block)` as the third parameter of the [`controller()` Twig function]([[= symfony_doc =]]/reference/twig_reference.html#controller) -so if the block type has a `cacheable_query_params` configuration, it will be passed for its cache to vary on those query parameters. +so if the block type has a `cacheable_query_params` configuration, it's passed for its cache to vary on those query parameters. Example usage: From c87e743d368a0104aa5ffe54398a5d6c62f89748 Mon Sep 17 00:00:00 2001 From: Adrien Dupuis <61695653+adriendupuis@users.noreply.github.com> Date: Tue, 3 Feb 2026 09:29:56 +0100 Subject: [PATCH 05/18] page_blocks.md: nobr in table --- docs/content_management/pages/page_blocks.md | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/docs/content_management/pages/page_blocks.md b/docs/content_management/pages/page_blocks.md index f5f7533d70..6375a32cf7 100644 --- a/docs/content_management/pages/page_blocks.md +++ b/docs/content_management/pages/page_blocks.md @@ -18,16 +18,16 @@ For information on how to create and configure new layouts for the Page, see [Pa Each configured block has an identifier and the following settings: -| Setting | Description | -|--------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| `name` | Name of the block used in the Page Builder interface. Translatable using the `ibexa_page_fieldtype` translation domain. | -| `category` | Category in the Page Builder **Page blocks** toolbox that the block is shown in. Translatable using the `ibexa_page_fieldtype` translation domain. | -| `thumbnail` | Thumbnail used in the Page Builder **Page blocks** toolbox. | -| `views` | Available [templates for the block](#block-templates). | -| `visible` | (Optional) Toggles the block's visibility in the Page Builder **Page blocks** toolbox. Remove the block from the layout before you publish another version of the page. | -| `configuration_template` | (Optional) Template for the block settings modal. | -| `attributes` | (Optional) List of [block attributes](page_block_attributes.md). | -| `cacheable_query_params` | (Optional) List of query parameters the block varies on. For example, if the block is paginated using `?page=ℕ` in the whole page URL, add `page` to this list. | +| Setting | Description | +|---------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `name` | Name of the block used in the Page Builder interface. Translatable using the `ibexa_page_fieldtype` translation domain. | +| `category` | Category in the Page Builder **Page blocks** toolbox that the block is shown in. Translatable using the `ibexa_page_fieldtype` translation domain. | +| `thumbnail` | Thumbnail used in the Page Builder **Page blocks** toolbox. | +| `views` | Available [templates for the block](#block-templates). | +| `visible` | (Optional) Toggles the block's visibility in the Page Builder **Page blocks** toolbox. Remove the block from the layout before you publish another version of the page. | +| `configuration_template` | (Optional) Template for the block settings modal. | +| `attributes` | (Optional) List of [block attributes](page_block_attributes.md). | +| `cacheable_query_params` | (Optional) List of query parameters the block varies on. For example, if the block is paginated using `?page=ℕ` in the whole page URL, add `page` to this list. | For example: From 393f8487338d687751dbdb354f62f0d229bafc91 Mon Sep 17 00:00:00 2001 From: Adrien Dupuis <61695653+adriendupuis@users.noreply.github.com> Date: Tue, 3 Feb 2026 11:00:28 +0100 Subject: [PATCH 06/18] pagefield.md: Move example to file Twig comments are not rendered when directly in the Markdown, moving this code to an included file fix the issue. --- code_samples/page/pagefield_layout.html.twig | 22 ++++++++++++++++++ .../field_type_reference/pagefield.md | 23 +------------------ 2 files changed, 23 insertions(+), 22 deletions(-) create mode 100644 code_samples/page/pagefield_layout.html.twig diff --git a/code_samples/page/pagefield_layout.html.twig b/code_samples/page/pagefield_layout.html.twig new file mode 100644 index 0000000000..13f77d721e --- /dev/null +++ b/code_samples/page/pagefield_layout.html.twig @@ -0,0 +1,22 @@ +
+ {# The required attribute for the displayed zone #} +
+ {# If a zone with [0] index contains any blocks #} + {% if zones[0].blocks %} + {# for each block #} + {% for block in blocks %} + {# create a new layer with appropriate ID #} +
+ {# render the block by using the "Ibexa\\Bundle\\FieldTypePage\\Controller\\BlockController::renderAction" controller #} + {# location.id is the ID of the Location of the current content item, block.id is the ID of the current block #} + {{ render_esi(controller('Ibexa\\Bundle\\FieldTypePage\\Controller\\BlockController::renderAction', { + 'locationId': locationId, + 'blockId': block.id, + 'versionNo': versionInfo.versionNo, + 'languageCode': field.languageCode + }, ibexa_append_cacheable_query_params(block))) }} +
+ {% endfor %} + {% endif %} +
+
diff --git a/docs/content_management/field_types/field_type_reference/pagefield.md b/docs/content_management/field_types/field_type_reference/pagefield.md index d725dd2ad3..92b2583cf6 100644 --- a/docs/content_management/field_types/field_type_reference/pagefield.md +++ b/docs/content_management/field_types/field_type_reference/pagefield.md @@ -69,26 +69,5 @@ Example usage: As a whole a sample layout could look as follows: ``` html+twig -
- {# The required attribute for the displayed zone #} -
- {# If a zone with [0] index contains any blocks #} - {% if zones[0].blocks %} - {# for each block #} - {% for block in blocks %} - {# create a new layer with appropriate ID #} -
- {# render the block by using the "Ibexa\\Bundle\\FieldTypePage\\Controller\\BlockController::renderAction" controller #} - {# location.id is the ID of the Location of the current content item, block.id is the ID of the current block #} - {{ render_esi(controller('Ibexa\\Bundle\\FieldTypePage\\Controller\\BlockController::renderAction', { - 'locationId': locationId, - 'blockId': block.id, - 'versionNo': versionInfo.versionNo, - 'languageCode': field.languageCode - }, ibexa_append_cacheable_query_params(block))) }} -
- {% endfor %} - {% endif %} -
-
+[[= include_file('code_samples/page/pagefield_layout.html.twig') =]] ``` From ed2dd9bb9bbbc469423d5b3bdadd9e5ba2620f74 Mon Sep 17 00:00:00 2001 From: Adrien Dupuis <61695653+adriendupuis@users.noreply.github.com> Date: Tue, 3 Feb 2026 12:36:04 +0100 Subject: [PATCH 07/18] pagefield.md: emphase on ibexa_append_cacheable_query_params optionality --- .../field_types/field_type_reference/pagefield.md | 5 +++-- docs/content_management/pages/page_blocks.md | 2 +- 2 files changed, 4 insertions(+), 3 deletions(-) diff --git a/docs/content_management/field_types/field_type_reference/pagefield.md b/docs/content_management/field_types/field_type_reference/pagefield.md index 92b2583cf6..02e754007f 100644 --- a/docs/content_management/field_types/field_type_reference/pagefield.md +++ b/docs/content_management/field_types/field_type_reference/pagefield.md @@ -52,8 +52,9 @@ The `renderAction` has the following parameters: | `versionNo` | Version number of the content item to render. | | `languageCode` | Language code of the content item to render. | -Use `ibexa_append_cacheable_query_params(block)` as the third parameter of the [`controller()` Twig function]([[= symfony_doc =]]/reference/twig_reference.html#controller) -so if the block type has a `cacheable_query_params` configuration, it's passed for its cache to vary on those query parameters. +Optionally, use `ibexa_append_cacheable_query_params(block)` as the third parameter of the [`controller()` Twig function]([[= symfony_doc =]]/reference/twig_reference.html#controller) +if this layout use custom block types with a [`cacheable_query_params` configuration](page_blocks.md#block-configuration), so it's passed for its cache to vary on those query parameters. +Notice that, on a fresh install, no frontend built-in blocks use this feature, only Dashboard blocks. Example usage: diff --git a/docs/content_management/pages/page_blocks.md b/docs/content_management/pages/page_blocks.md index 6375a32cf7..48c18c6705 100644 --- a/docs/content_management/pages/page_blocks.md +++ b/docs/content_management/pages/page_blocks.md @@ -27,7 +27,7 @@ Each configured block has an identifier and the following settings: | `visible` | (Optional) Toggles the block's visibility in the Page Builder **Page blocks** toolbox. Remove the block from the layout before you publish another version of the page. | | `configuration_template` | (Optional) Template for the block settings modal. | | `attributes` | (Optional) List of [block attributes](page_block_attributes.md). | -| `cacheable_query_params` | (Optional) List of query parameters the block varies on. For example, if the block is paginated using `?page=ℕ` in the whole page URL, add `page` to this list. | +| `cacheable_query_params` | (Optional) List of query parameters the block varies on. For example, if the block is paginated using `?page=ℕ` in the whole page URL, add `page` to this list. | For example: From afb4bf52df6840acdca745507493fcc4e81a9168 Mon Sep 17 00:00:00 2001 From: Adrien Dupuis <61695653+adriendupuis@users.noreply.github.com> Date: Tue, 3 Feb 2026 12:43:27 +0100 Subject: [PATCH 08/18] pagefield.md: emphase on ibexa_append_cacheable_query_params optionality --- .../field_types/field_type_reference/pagefield.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/content_management/field_types/field_type_reference/pagefield.md b/docs/content_management/field_types/field_type_reference/pagefield.md index 02e754007f..6cdefab893 100644 --- a/docs/content_management/field_types/field_type_reference/pagefield.md +++ b/docs/content_management/field_types/field_type_reference/pagefield.md @@ -54,7 +54,7 @@ The `renderAction` has the following parameters: Optionally, use `ibexa_append_cacheable_query_params(block)` as the third parameter of the [`controller()` Twig function]([[= symfony_doc =]]/reference/twig_reference.html#controller) if this layout use custom block types with a [`cacheable_query_params` configuration](page_blocks.md#block-configuration), so it's passed for its cache to vary on those query parameters. -Notice that, on a fresh install, no frontend built-in blocks use this feature, only Dashboard blocks. +Notice that, on a fresh install, no frontend built-in blocks use this feature, but it's only used by [Dashboard blocks]([[= user_doc =]]/getting_started/dashboard/dashboard_block_reference/) My content and Review queue. Example usage: From aaf1d093c62a5ea3f2c9c7fbff24e33687ccd94f Mon Sep 17 00:00:00 2001 From: Adrien Dupuis <61695653+adriendupuis@users.noreply.github.com> Date: Tue, 3 Feb 2026 13:19:50 +0100 Subject: [PATCH 09/18] data-ez-block-id -> data-ibexa-block-id --- code_samples/page/pagefield_layout.html.twig | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/code_samples/page/pagefield_layout.html.twig b/code_samples/page/pagefield_layout.html.twig index 13f77d721e..0eacab3fc5 100644 --- a/code_samples/page/pagefield_layout.html.twig +++ b/code_samples/page/pagefield_layout.html.twig @@ -6,7 +6,7 @@ {# for each block #} {% for block in blocks %} {# create a new layer with appropriate ID #} -
+
{# render the block by using the "Ibexa\\Bundle\\FieldTypePage\\Controller\\BlockController::renderAction" controller #} {# location.id is the ID of the Location of the current content item, block.id is the ID of the current block #} {{ render_esi(controller('Ibexa\\Bundle\\FieldTypePage\\Controller\\BlockController::renderAction', { From 11768ad72b861d1c2eab5c251b474d1309f22c4a Mon Sep 17 00:00:00 2001 From: Adrien Dupuis <61695653+adriendupuis@users.noreply.github.com> Date: Tue, 3 Feb 2026 14:18:04 +0100 Subject: [PATCH 10/18] page_twig_functions.md --- docs/templating/twig_function_reference/page_twig_functions.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/templating/twig_function_reference/page_twig_functions.md b/docs/templating/twig_function_reference/page_twig_functions.md index b9263e0a0f..81f7bdd099 100644 --- a/docs/templating/twig_function_reference/page_twig_functions.md +++ b/docs/templating/twig_function_reference/page_twig_functions.md @@ -10,6 +10,7 @@ month_change: true ## `ibexa_append_cacheable_query_params()` Get the query parameters of a page block as [configured in `cacheable_query_params`](page_blocks.md#block-configuration). +If the block type has no configured query parameters, an empty array is returned. ```twig {{ render_esi(controller('Ibexa\\Bundle\\FieldTypePage\\Controller\\BlockController::renderAction', { From 86cd14c58a8d09701e3a22cabb26af59633a82e5 Mon Sep 17 00:00:00 2001 From: Adrien Dupuis <61695653+adriendupuis@users.noreply.github.com> Date: Tue, 3 Feb 2026 14:37:56 +0100 Subject: [PATCH 11/18] pagefield.md: Link to page_twig_functions.md --- .../field_types/field_type_reference/pagefield.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/content_management/field_types/field_type_reference/pagefield.md b/docs/content_management/field_types/field_type_reference/pagefield.md index 6cdefab893..1e4f5853a2 100644 --- a/docs/content_management/field_types/field_type_reference/pagefield.md +++ b/docs/content_management/field_types/field_type_reference/pagefield.md @@ -52,7 +52,7 @@ The `renderAction` has the following parameters: | `versionNo` | Version number of the content item to render. | | `languageCode` | Language code of the content item to render. | -Optionally, use `ibexa_append_cacheable_query_params(block)` as the third parameter of the [`controller()` Twig function]([[= symfony_doc =]]/reference/twig_reference.html#controller) +Optionally, use [`ibexa_append_cacheable_query_params(block)`](page_twig_functions.md#ibexa_append_cacheable_query_params) as the third parameter of the [`controller()` Twig function]([[= symfony_doc =]]/reference/twig_reference.html#controller) if this layout use custom block types with a [`cacheable_query_params` configuration](page_blocks.md#block-configuration), so it's passed for its cache to vary on those query parameters. Notice that, on a fresh install, no frontend built-in blocks use this feature, but it's only used by [Dashboard blocks]([[= user_doc =]]/getting_started/dashboard/dashboard_block_reference/) My content and Review queue. From 38085c22c13fba79c633debc197954dbc464369a Mon Sep 17 00:00:00 2001 From: Adrien Dupuis <61695653+adriendupuis@users.noreply.github.com> Date: Tue, 3 Feb 2026 14:42:35 +0100 Subject: [PATCH 12/18] pagefield.md: typo --- .../field_types/field_type_reference/pagefield.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/content_management/field_types/field_type_reference/pagefield.md b/docs/content_management/field_types/field_type_reference/pagefield.md index 1e4f5853a2..44fb07b54d 100644 --- a/docs/content_management/field_types/field_type_reference/pagefield.md +++ b/docs/content_management/field_types/field_type_reference/pagefield.md @@ -53,7 +53,7 @@ The `renderAction` has the following parameters: | `languageCode` | Language code of the content item to render. | Optionally, use [`ibexa_append_cacheable_query_params(block)`](page_twig_functions.md#ibexa_append_cacheable_query_params) as the third parameter of the [`controller()` Twig function]([[= symfony_doc =]]/reference/twig_reference.html#controller) -if this layout use custom block types with a [`cacheable_query_params` configuration](page_blocks.md#block-configuration), so it's passed for its cache to vary on those query parameters. +if this layout uses custom block types with a [`cacheable_query_params` configuration](page_blocks.md#block-configuration), so it's passed for its HTTP cache to vary on those query parameters. Notice that, on a fresh install, no frontend built-in blocks use this feature, but it's only used by [Dashboard blocks]([[= user_doc =]]/getting_started/dashboard/dashboard_block_reference/) My content and Review queue. Example usage: From 4a074103ca821f17766e02288e59b10fbc075bc8 Mon Sep 17 00:00:00 2001 From: Adrien Dupuis <61695653+adriendupuis@users.noreply.github.com> Date: Tue, 3 Feb 2026 16:01:34 +0100 Subject: [PATCH 13/18] Apply suggestions from code review MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Marek Nocoń --- .../field_types/field_type_reference/pagefield.md | 6 +++--- .../twig_function_reference/page_twig_functions.md | 2 +- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/content_management/field_types/field_type_reference/pagefield.md b/docs/content_management/field_types/field_type_reference/pagefield.md index 44fb07b54d..df849f4323 100644 --- a/docs/content_management/field_types/field_type_reference/pagefield.md +++ b/docs/content_management/field_types/field_type_reference/pagefield.md @@ -52,9 +52,9 @@ The `renderAction` has the following parameters: | `versionNo` | Version number of the content item to render. | | `languageCode` | Language code of the content item to render. | -Optionally, use [`ibexa_append_cacheable_query_params(block)`](page_twig_functions.md#ibexa_append_cacheable_query_params) as the third parameter of the [`controller()` Twig function]([[= symfony_doc =]]/reference/twig_reference.html#controller) -if this layout uses custom block types with a [`cacheable_query_params` configuration](page_blocks.md#block-configuration), so it's passed for its HTTP cache to vary on those query parameters. -Notice that, on a fresh install, no frontend built-in blocks use this feature, but it's only used by [Dashboard blocks]([[= user_doc =]]/getting_started/dashboard/dashboard_block_reference/) My content and Review queue. +Optionally, if the layout uses custom block types with a [`cacheable_query_params configuration`](page_blocks.md#block-configuration), pass [`ibexa_append_cacheable_query_params(block)`](page_twig_functions.md#ibexa_append_cacheable_query_params) as the third argument to the [`controller()` Twig function]([[= symfony_doc =]]/reference/twig_reference.html#controller) so that the HTTP cache can vary based on those query parameters. + +Note that in a fresh installation, none of the built-in frontend blocks use this feature; it is currently only used by the [Dashboard blocks[([[= user_doc =]]/getting_started/dashboard/dashboard_block_reference/): "My content" and "Review queue". Example usage: diff --git a/docs/templating/twig_function_reference/page_twig_functions.md b/docs/templating/twig_function_reference/page_twig_functions.md index 81f7bdd099..056d9b1e4a 100644 --- a/docs/templating/twig_function_reference/page_twig_functions.md +++ b/docs/templating/twig_function_reference/page_twig_functions.md @@ -1,5 +1,5 @@ --- -description: Page field and page block Twig functions access to configuration. +description: Page field and page block Twig functions provide access to configuration. page_type: reference edition: experience month_change: true From 190f9c5050936107ecd28390d2b433ff33c70d26 Mon Sep 17 00:00:00 2001 From: Adrien Dupuis <61695653+adriendupuis@users.noreply.github.com> Date: Tue, 3 Feb 2026 16:22:51 +0100 Subject: [PATCH 14/18] pagefield.md: Fix style and syntax --- .../field_types/field_type_reference/pagefield.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/content_management/field_types/field_type_reference/pagefield.md b/docs/content_management/field_types/field_type_reference/pagefield.md index df849f4323..7f63610a7f 100644 --- a/docs/content_management/field_types/field_type_reference/pagefield.md +++ b/docs/content_management/field_types/field_type_reference/pagefield.md @@ -54,7 +54,7 @@ The `renderAction` has the following parameters: Optionally, if the layout uses custom block types with a [`cacheable_query_params configuration`](page_blocks.md#block-configuration), pass [`ibexa_append_cacheable_query_params(block)`](page_twig_functions.md#ibexa_append_cacheable_query_params) as the third argument to the [`controller()` Twig function]([[= symfony_doc =]]/reference/twig_reference.html#controller) so that the HTTP cache can vary based on those query parameters. -Note that in a fresh installation, none of the built-in frontend blocks use this feature; it is currently only used by the [Dashboard blocks[([[= user_doc =]]/getting_started/dashboard/dashboard_block_reference/): "My content" and "Review queue". +In a fresh installation, none of the built-in frontend blocks use this feature. It's only used by the [Dashboard blocks]([[= user_doc =]]/getting_started/dashboard/dashboard_block_reference/): "My content" and "Review queue". Example usage: From 4430edce0dc2db6e4386c83cbbdb2adb437d4545 Mon Sep 17 00:00:00 2001 From: Adrien Dupuis <61695653+adriendupuis@users.noreply.github.com> Date: Wed, 4 Feb 2026 09:19:25 +0100 Subject: [PATCH 15/18] page_blocks.md: rewording --- docs/content_management/pages/page_blocks.md | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/docs/content_management/pages/page_blocks.md b/docs/content_management/pages/page_blocks.md index 48c18c6705..bf78e5f5f9 100644 --- a/docs/content_management/pages/page_blocks.md +++ b/docs/content_management/pages/page_blocks.md @@ -18,16 +18,16 @@ For information on how to create and configure new layouts for the Page, see [Pa Each configured block has an identifier and the following settings: -| Setting | Description | -|---------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| `name` | Name of the block used in the Page Builder interface. Translatable using the `ibexa_page_fieldtype` translation domain. | -| `category` | Category in the Page Builder **Page blocks** toolbox that the block is shown in. Translatable using the `ibexa_page_fieldtype` translation domain. | -| `thumbnail` | Thumbnail used in the Page Builder **Page blocks** toolbox. | -| `views` | Available [templates for the block](#block-templates). | -| `visible` | (Optional) Toggles the block's visibility in the Page Builder **Page blocks** toolbox. Remove the block from the layout before you publish another version of the page. | -| `configuration_template` | (Optional) Template for the block settings modal. | -| `attributes` | (Optional) List of [block attributes](page_block_attributes.md). | -| `cacheable_query_params` | (Optional) List of query parameters the block varies on. For example, if the block is paginated using `?page=ℕ` in the whole page URL, add `page` to this list. | +| Setting | Description | +|---------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `name` | Name of the block used in the Page Builder interface. Translatable using the `ibexa_page_fieldtype` translation domain. | +| `category` | Category in the Page Builder **Page blocks** toolbox that the block is shown in. Translatable using the `ibexa_page_fieldtype` translation domain. | +| `thumbnail` | Thumbnail used in the Page Builder **Page blocks** toolbox. | +| `views` | Available [templates for the block](#block-templates). | +| `visible` | (Optional) Toggles the block's visibility in the Page Builder **Page blocks** toolbox. Remove the block from the layout before you publish another version of the page. | +| `configuration_template` | (Optional) Template for the block settings modal. | +| `attributes` | (Optional) List of [block attributes](page_block_attributes.md). | +| `cacheable_query_params` | (Optional) List of query parameters the block's ESI HTTP cache varies on. For example, if the block is paginated using `?page=ℕ` from the page URL, add `page` to this list. | For example: From 44d42b2b1ec176370266ea2eb1a737c16719a339 Mon Sep 17 00:00:00 2001 From: Adrien Dupuis <61695653+adriendupuis@users.noreply.github.com> Date: Wed, 4 Feb 2026 09:39:31 +0100 Subject: [PATCH 16/18] page_blocks.md: rewording+link --- .../field_type_reference/pagefield.md | 2 +- docs/content_management/pages/page_blocks.md | 20 +++++++++---------- .../http_cache/http_cache_configuration.md | 2 +- 3 files changed, 12 insertions(+), 12 deletions(-) diff --git a/docs/content_management/field_types/field_type_reference/pagefield.md b/docs/content_management/field_types/field_type_reference/pagefield.md index 7f63610a7f..0bf9ac1f6f 100644 --- a/docs/content_management/field_types/field_type_reference/pagefield.md +++ b/docs/content_management/field_types/field_type_reference/pagefield.md @@ -41,7 +41,7 @@ You can access them using twig (for example, `{{ zones[0].id }}` ). Each div that's a zone should have the `data-ibexa-zone-id` attribute with zone ID as a value for a zone container. -To render a block inside the layout, use the Twig `render_esi()` function to call `Ibexa\\Bundle\\FieldTypePage\\Controller\\BlockController::renderAction`. +To render a block inside the layout, use the Twig [`render_esi()`]([[= symfony_doc =]]/reference/twig_reference.html#render-esi) function to call `Ibexa\\Bundle\\FieldTypePage\\Controller\\BlockController::renderAction`. The `renderAction` has the following parameters: diff --git a/docs/content_management/pages/page_blocks.md b/docs/content_management/pages/page_blocks.md index bf78e5f5f9..e85ffaf535 100644 --- a/docs/content_management/pages/page_blocks.md +++ b/docs/content_management/pages/page_blocks.md @@ -18,16 +18,16 @@ For information on how to create and configure new layouts for the Page, see [Pa Each configured block has an identifier and the following settings: -| Setting | Description | -|---------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| `name` | Name of the block used in the Page Builder interface. Translatable using the `ibexa_page_fieldtype` translation domain. | -| `category` | Category in the Page Builder **Page blocks** toolbox that the block is shown in. Translatable using the `ibexa_page_fieldtype` translation domain. | -| `thumbnail` | Thumbnail used in the Page Builder **Page blocks** toolbox. | -| `views` | Available [templates for the block](#block-templates). | -| `visible` | (Optional) Toggles the block's visibility in the Page Builder **Page blocks** toolbox. Remove the block from the layout before you publish another version of the page. | -| `configuration_template` | (Optional) Template for the block settings modal. | -| `attributes` | (Optional) List of [block attributes](page_block_attributes.md). | -| `cacheable_query_params` | (Optional) List of query parameters the block's ESI HTTP cache varies on. For example, if the block is paginated using `?page=ℕ` from the page URL, add `page` to this list. | +| Setting | Description | +|---------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `name` | Name of the block used in the Page Builder interface. Translatable using the `ibexa_page_fieldtype` translation domain. | +| `category` | Category in the Page Builder **Page blocks** toolbox that the block is shown in. Translatable using the `ibexa_page_fieldtype` translation domain. | +| `thumbnail` | Thumbnail used in the Page Builder **Page blocks** toolbox. | +| `views` | Available [templates for the block](#block-templates). | +| `visible` | (Optional) Toggles the block's visibility in the Page Builder **Page blocks** toolbox. Remove the block from the layout before you publish another version of the page. | +| `configuration_template` | (Optional) Template for the block settings modal. | +| `attributes` | (Optional) List of [block attributes](page_block_attributes.md). | +| `cacheable_query_params` | (Optional) List of query parameters the block's [ESI HTTP cache](http_cache_configuration.md#when-to-use-esi) varies on.
For example, if the block is paginated using `?page=ℕ` from the page URL, add `page` to this list.
See [`ibexa_append_cacheable_query_params()`Twig function](page_twig_functions.md#ibexa_append_cacheable_query_params). | For example: diff --git a/docs/infrastructure_and_maintenance/cache/http_cache/http_cache_configuration.md b/docs/infrastructure_and_maintenance/cache/http_cache/http_cache_configuration.md index 02e0e99348..44373504cd 100644 --- a/docs/infrastructure_and_maintenance/cache/http_cache/http_cache_configuration.md +++ b/docs/infrastructure_and_maintenance/cache/http_cache/http_cache_configuration.md @@ -92,4 +92,4 @@ You should not use ESI for parts that are effectively uncached, because your rev !!! note "ESI limitations with the URIElement SiteAccess matcher" - Is isn't possible to share ESIs across the SiteAccesses when using URI matching as URI contains the SiteAccess name encoded in its path information. + It isn't possible to share ESIs across the SiteAccesses when using URI matching as URI contains the SiteAccess name encoded in its path information. From 3481d790e0e9012fa30c4637ad5d1c34fa5b8c60 Mon Sep 17 00:00:00 2001 From: Adrien Dupuis <61695653+adriendupuis@users.noreply.github.com> Date: Wed, 4 Feb 2026 10:01:16 +0100 Subject: [PATCH 17/18] Update docs/content_management/field_types/field_type_reference/pagefield.md Co-authored-by: Bartek Wajda --- .../field_types/field_type_reference/pagefield.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/content_management/field_types/field_type_reference/pagefield.md b/docs/content_management/field_types/field_type_reference/pagefield.md index 0bf9ac1f6f..2d98ff6509 100644 --- a/docs/content_management/field_types/field_type_reference/pagefield.md +++ b/docs/content_management/field_types/field_type_reference/pagefield.md @@ -52,7 +52,7 @@ The `renderAction` has the following parameters: | `versionNo` | Version number of the content item to render. | | `languageCode` | Language code of the content item to render. | -Optionally, if the layout uses custom block types with a [`cacheable_query_params configuration`](page_blocks.md#block-configuration), pass [`ibexa_append_cacheable_query_params(block)`](page_twig_functions.md#ibexa_append_cacheable_query_params) as the third argument to the [`controller()` Twig function]([[= symfony_doc =]]/reference/twig_reference.html#controller) so that the HTTP cache can vary based on those query parameters. +If your block needs to be dependent on query parameters like "page" and you already configured your custom block with a [`cacheable_query_params configuration`](page_blocks.md#block-configuration), pass [`ibexa_append_cacheable_query_params(block)`](page_twig_functions.md#ibexa_append_cacheable_query_params) as the third argument to the [`controller()` Twig function]([[= symfony_doc =]]/reference/twig_reference.html#controller) so that the HTTP cache can vary based on those query parameters. In a fresh installation, none of the built-in frontend blocks use this feature. It's only used by the [Dashboard blocks]([[= user_doc =]]/getting_started/dashboard/dashboard_block_reference/): "My content" and "Review queue". From b76ddbab9ae4635c94ac22b110f4f27b22bcffbd Mon Sep 17 00:00:00 2001 From: Adrien Dupuis <61695653+adriendupuis@users.noreply.github.com> Date: Wed, 4 Feb 2026 10:03:41 +0100 Subject: [PATCH 18/18] pagefield.md: Rewording --- .../field_types/field_type_reference/pagefield.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/content_management/field_types/field_type_reference/pagefield.md b/docs/content_management/field_types/field_type_reference/pagefield.md index 2d98ff6509..b8497dc0d2 100644 --- a/docs/content_management/field_types/field_type_reference/pagefield.md +++ b/docs/content_management/field_types/field_type_reference/pagefield.md @@ -54,7 +54,7 @@ The `renderAction` has the following parameters: If your block needs to be dependent on query parameters like "page" and you already configured your custom block with a [`cacheable_query_params configuration`](page_blocks.md#block-configuration), pass [`ibexa_append_cacheable_query_params(block)`](page_twig_functions.md#ibexa_append_cacheable_query_params) as the third argument to the [`controller()` Twig function]([[= symfony_doc =]]/reference/twig_reference.html#controller) so that the HTTP cache can vary based on those query parameters. -In a fresh installation, none of the built-in frontend blocks use this feature. It's only used by the [Dashboard blocks]([[= user_doc =]]/getting_started/dashboard/dashboard_block_reference/): "My content" and "Review queue". +In a fresh installation, the feature is only used by the back office's [Dashboard blocks]([[= user_doc =]]/getting_started/dashboard/dashboard_block_reference/): "My content" and "Review queue". Example usage: