Layouts Ibexa Relation List Query Laravel Package

Getting Started

1. Install via Composer alongside the core integration:

   composer require netgen/layouts-ibexa-relation-list-query
   

   Check the composer.json constraints first — this package depends on a specific netgen/layouts-ibexa line (and transitively on an Ibexa version). With 0 stars and no dependents, verify the matrix against your Ibexa/Netgen versions before committing.

2. Register the bundle in config/bundles.php. It follows Netgen's NetgenLayouts...Bundle naming; register it after NetgenLayoutsIbexaBundle so the query type can consume Ibexa services. Clear the container cache afterwards (bin/console cache:clear).

3. Where to look first: the package's README.md, then the query type service definition and its config form (look under lib/ or src/ for a QueryType class and RelationList in its name). That form tells you exactly which parameters the query expects (source content, field identifier, limit/offset). Confirm it's registered by grepping the container for the netgen_layouts.query_type tag:

   bin/console debug:container --tag=netgen_layouts.query_type
   

4. First use case: an editor curates "Related articles" on an Article content item using an ibexa_relation_list field. Create a List block in a layout (List is the standard block type that supports queries), open its Query tab, choose the relation-list query type, point it at that content item and the field identifier. The block now renders the field's related items — curation lives in Ibexa, rendering/paging lives in Layouts.

Implementation Patterns

• Editorial curation, decoupled rendering. The pattern this package is built for: editors pick related items in the CMS (with drafts, workflow, versioning), and Layouts resolves them into block items at render time. No hardcoded content IDs in layout configs, no duplicate manual item picking.

• Dynamic "current content" parameters. Netgen Layouts supports query parameters resolved at runtime. Parameterise the source content so one block works across many pages — e.g. bind it to the currently displayed content's ID rather than a fixed ID. This is the big win for reusable layout templates: drop the block once, and every Article page renders its own relations.

• One block per relation field. Content items often have several relation fields (related_articles, related_products, see_also). Configure separate List blocks per field; each gets its own template/item view, pagination and limit.

• Lean on List block features. Set limit/offset (or the block's pagination) on the query so you get paging, empty-state handling and block caching for free instead of building a custom loop in the template.

• Render through the standard view layer. Items returned are Ibexa content (or locations — check which the query yields). They are rendered through your regular Ibexa content view templates, so existing overrides and view config apply automatically. Override the List block's item template only when you need a different teaser than the content's default view.

• Cache/invalidation. Layouts caches rendered blocks. The netgen/layouts-ibexa integration hooks into Ibexa content change events to invalidate layout caches — verify that publishing a related item actually clears the block in your setup, especially if you use a shared HTTP cache in front of the app.

Gotchas and Tips

• Block type matters. Only query-capable block types (e.g. List) expose the Query tab. If you can't see the query form, you've added a block that doesn't support queries, not a query-type registration problem.

• Content ID vs Location ID. Relation list fields store Content IDs. The query config must ask for a content ID; if your dynamic parameter only exposes a location ID (common on location-driven routes), you'll need to resolve location → content first, or supply both and let the query pick. A mismatched ID silently returns an empty block rather than an error.

• Empty relations fail silently. An unset/empty relation list is a legitimate empty result. Always provide an empty-state in the block template; don't debug for hours assuming the query is broken.

• Versioning and preview. Relations resolve against the published version. In preview of an unpublished draft, newly added relations may not appear — expected behaviour, not a bug.

• Permissions and hidden content. Decide whether related items that are hidden or unreadable for the current user should be filtered. Standard Ibexa visibility filters apply to content views, but the count and pagination totals can be based on unfiltered relation entries, giving short pages — test with restricted users.

• Language fallback. Relations are stored language-agnostically; rendering follows Ibexa's language configuration. Missing translations fall back (or are filtered) according to ibexa.system.*.variavlanguages-style settings, so the same relations can yield different numbers of items per siteaccess.

• Version compatibility. The Netgen Layouts query-type API differs between major versions. Pin the package (and netgen/layouts-ibexa) in composer.json and upgrade them together; don't let Composer float this package independently.

• Debugging. For a block that renders nothing: (a) confirm the query type is in the container tag list; (b) dump the query configuration in the block template/controller to see the resolved parameters; (c) re-check the field identifier string — a typo yields an empty relation set, not an exception.

• Extension points. The query type is registered as a regular service, so you can decorate it or override its service definition to add filtering, ordering or extra configuration options without forking. If you need behaviour beyond the form, that's the route — but keep customisations in a local bundle, since this package is young and its internals may move.