ibexa · adriendupuis · Feb 2, 2026 · Feb 2, 2026 · Feb 2, 2026 · Feb 2, 2026
diff --git a/code_samples/page/pagefield_layout.html.twig b/code_samples/page/pagefield_layout.html.twig
@@ -0,0 +1,22 @@
+<div>
+    {# The required attribute for the displayed zone #}
+    <div data-ibexa-zone-id="{{ zones[0].id }}">
+        {# 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 #}
+                <div class="landing-page__block block_{{ block.type }}" data-ibexa-block-id="{{ block.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))) }}
+                </div>
+            {% endfor %}
+        {% endif %}
+    </div>
+</div>
diff --git 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 @@
 
 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:
 
@@ -52,6 +52,10 @@
 | `versionNo`    | Version number of the content item to render.                                    |
 | `languageCode` | Language code of the content item to render.                                     |
 
+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, 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:
 
 ``` html+twig
@@ -60,32 +64,11 @@
     '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:
 
 ``` html+twig
-<div>
-    {# The required attribute for the displayed zone #}
-    <div data-ibexa-zone-id="{{ zones[0].id }}">
-        {# 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 #}
-                <div class="landing-page__block block_{{ block.type }}" data-ez-block-id="{{ block.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
-                    })) }}
-                </div>
-            {% endfor %}
-        {% endif %}
-    </div>
-</div>
+[[= include_file('code_samples/page/pagefield_layout.html.twig') =]]
 ```
diff --git a/docs/content_management/pages/page_blocks.md b/docs/content_management/pages/page_blocks.md
@@ -18,15 +18,16 @@
 
 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).                                                                                              |
+| 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).                                                                                                        |
+| <nobr>`cacheable_query_params`</nobr> | (Optional) List of query parameters the block's [ESI HTTP cache](http_cache_configuration.md#when-to-use-esi) varies on.<br>For example, if the block is paginated using `?page=ℕ` from the page URL, add `page` to this list.<br>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
@@ -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.
diff --git a/docs/release_notes/ibexa_dxp_v5.0.md b/docs/release_notes/ibexa_dxp_v5.0.md
@@ -10,6 +10,35 @@ month_change: false
 
 <div class="release-notes" markdown="1">
 
+[[% set version = 'v5.0.X' %]]
+
+[[= release_note_entry_begin("Ibexa DXP " + version, 'YYYY-MM-DD', ['Experience', 'Commerce']) =]]
+
+### Improved HTTP caching for Page Builder and dashboard blocks
+
+You can now indicate which [query parameters](https://en.wikipedia.org/wiki/Query_string) must be used as keys when generating [HTTP cache](http_cache.md) for block requests.
+
+This allows you to improve performance for blocks by utilizing HTTP cache more effectively, for example, for paginated blocks in the [dashboard](customize_dashboard.md).
+
+To set it up, use the new `cacheable_query_params` [block setting](page_blocks.md#block-configuration).
+
+Then, adjust your [layouts](render_page.md#configure-layout) and pass the parameters to [Symfony's `controller function`]([[= symfony_doc =]]/reference/twig_reference.html#controller) by using the new `ibexa_append_cacheable_query_params` Twig function, as in the example below:
+
+``` html+twig
+{{ render_esi(controller('Ibexa\\Bundle\\FieldTypePage\\Controller\\BlockController::renderAction',
+    {
+        'locationId': locationId,
+        'contentId': contentInfo.id,
+        'blockId': block.id,
+        'versionNo': versionInfo.versionNo,
+        'languageCode': field.languageCode
+    },
+    ibexa_append_cacheable_query_params(block)
+)) }}
+```
+
+[[= release_note_entry_end() =]]
+
 [[% set version = 'v5.0.5' %]]
 
 [[= release_note_entry_begin("Ibexa DXP " + version, '2026-01-15', ['Headless', 'Experience', 'Commerce']) =]]

diff --git a/docs/templating/twig_function_reference/page_twig_functions.md b/docs/templating/twig_function_reference/page_twig_functions.md
@@ -0,0 +1,33 @@
+---
+description: Page field and page block Twig functions provide 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).
+If the block type has no configured query parameters, an empty array is returned.
+
+```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
@@ -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",

diff --git 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
Original file line number	Diff line number	Diff line change
Expand Up		@@ -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.