Layouts Standard Laravel Package

Getting Started

netgen/layouts-standard is a companion package — it does nothing on its own. It ships ready-made block definitions (title, text, image, collection, gallery, embed, etc.) plus layout and block view templates for netgen/layouts-core. Treat it as a starter kit you extend, not a framework you configure from scratch.

Minimum setup:

composer require netgen/layouts-standard

Register the bundle in config/bundles.php:

Netgen\Bundle\LayoutsStandardBundle\NetgenLayoutsStandardBundle::class => ['all' => true],

Then run the core install (migrations + assets) because layouts-standard block definitions write rows into the nglayouts tables that core owns:

bin/console netgen:layouts:install

First place to look: the bundle's Resources/config/layouts.yaml (block definitions, view types, item view types) and Resources/views/ (Twig templates). That YAML is the source of truth for what you can place in the admin UI and which template renders it.

First use case — put a text block on the homepage:

1. Open /admin (Netgen Layouts admin), create a layout, map it to the homepage route via the Rule target.
2. Add a zone, drop a Text block into it, fill in the content.
3. Front-end request to / now renders through your layout resolver and the block's registered view.

Only start writing code once you've confirmed the standard blocks render — most "it's broken" reports are routing/targeting issues, not template issues.

Implementation Patterns

Custom block via YAML + Twig. Define a block in your app's config/packages/netgen_layouts.yaml, pointing at view types:

netgen_layouts:
    block_definitions:
        my_hero:
            name: 'Hero banner'
            icon: '/bundles/netgenlayoutsstandard/images/blocks/text.svg'
            defaults:
                view_type: standard\hero
            views:
                standard\hero:
                    name: 'Standard'
                    template: '@App/blocks/hero.html.twig'

The template key resolves through the Twig loader, so @App/... and @NetgenLayoutsStandard/... both work. Copy standard templates out of vendor/netgen/layouts-standard/src/bundle/Resources/views/ before editing — don't edit vendor.

Collection blocks are the workhorse. A collection block needs a query type (what items) and an item view type (how each renders). Two integration patterns dominate:

• Manual collections — editors pick items in admin. Configure with collection query type; use default item view type overridden per content type.
• Dynamic collections — bind items via a custom query type service tagged netgen_layouts.query_type. Useful for "latest 5 articles in this category."

Block plugin for behaviour. When a block needs data or logic beyond config (e.g., an API-fed widget), implement BlockPluginInterface and tag the service netgen_layouts.block_plugin. The plugin's accept() decides applicability; preCache() / postCache() are the hooks — do heavy lookups in preCache() and stash on the block via $block->setParameter().

Controller-driven blocks. For anything editor-configurable but not a collection, define a custom block view whose template calls a render(controller(...)) — keeps layout templates dumb and lets you test the controller normally. This is often cleaner than a plugin.

Override view types per content type. In the admin, a contentful block's item view type can be different per content type (article vs. page). That's the idiomatic way to support heterogeneous content without {% if %} spaghetti.

Targeting via rules, not code. Layouts attach to pages through rule targets — route, path, content_type, section. Prefer setting these in the admin; when you need programmatic control, register a custom RuleTarget service rather than hardcoding in a controller.

Caching. Layout resolution and rendering are cached. After changing block definitions or YAML, bin/console cache:clear. In dev, the netgen_layouts profiler panel shows which layout resolved and which blocks were cached.

Gotchas and Tips

• Bundle order matters. NetgenLayoutsStandardBundle must be registered after NetgenLayoutsBundle. If the standard blocks don't appear in admin, check config/bundles.php ordering first.
• netgen:layouts:install is per-database. New environments need migrations run — the standard blocks are database rows, not just code. A fresh deploy that skips this renders an empty admin.
• View type strings are namespaced. standard\text is not text. Typos produce silent fallbacks to a default template or nothing at all. Grep the standard YAML for the exact string before guessing.
• Editor config vs. code. Block definitions live in YAML; the instances live in the DB. Deleting a block definition in code does not delete placed blocks — orphaned blocks remain in the admin and may error on render. Add a migration/cleanup or leave the definition until blocks are removed.
• Template override path is templates/bundles/NetgenLayoutsStandardBundle/... if you want bundle-level overrides without touching vendor. Per-project block templates in @App/blocks/ are usually cleaner, but the bundle override path is the fallback for admin-preview and mail templates.
• Collection queries need a valid "items resolver" for the content type. A collection that returns items of a type with no registered resolver throws at render time, not at admin time — so editors think it works until publish. Register resolvers for every content type you expose.
• preCache() runs on every cache warm, including admin previews. Guard against slow external calls; wrap in try/catch and log rather than throwing, or the admin becomes unusable when an API is down.
• Asset install. The admin UI needs published assets: bin/console assets:install --symlink in dev, or the standard webpack/asset pipeline in prod. A blank admin with 404s on CSS is almost always this.
• Symfony compatibility is tight. layouts-standard pins a major Netgen Layouts minor; check composer show netgen/layouts-standard requires before upgrading Symfony. The bundle has lagged core historically — don't bump blind.
• Extension point for custom view types: if you need a new rendering strategy (e.g., "carousel" view), register a block view type in YAML — no PHP needed. Only reach for a block plugin when behaviour, not presentation, differs.
• Debugging empty output: enable the netgen_layouts profiler panel, check the resolved layout, then check whether the target rule matched. 90% of "block not showing" cases are a non-matching rule target, not a template bug.