README

Symfony bundle that connects a Doctrine entity to the Celebrimbor headless visual page builder. It ships no blocks — you bring your own JS block registry. The bundle provides the PHP plumbing:

• a contract (HasPageBuilderContent) + Doctrine trait for your model,
• a Form type (PageBuilderType) wired to the Symfony UX / Stimulus controller from @n-ramos/celebrimbor-symfony,
• a per-block Twig preview renderer (CelebrimborRenderer) and an AbstractPreviewController you extend with a single route.

The JavaScript half (the <my-page-builder> web component, the Stimulus controller, your block registry) lives in the npm package @n-ramos/celebrimbor-symfony, installed via AssetMapper/importmap.

Install

composer require n-ramos/celebrimbor-bundle
php bin/console importmap:require @n-ramos/celebrimbor-symfony

Register your blocks once in your AssetMapper entry (e.g. assets/app.js):

import { defineCelebrimbor } from "@n-ramos/celebrimbor-symfony";
import "@n-ramos/celebrimbor-symfony/styles.css";
import { createBlockRegistry } from "@n-ramos/celebrimbor-core";

const registry = createBlockRegistry();
// registry.register(myHeroBlock); ...
defineCelebrimbor({ registry });

1. The model

Implement the contract and use the trait. The trait maps a nullable JSON document column and stores the editor payload raw.

use Doctrine\ORM\Mapping as ORM;
use NRamos\CelebrimborBundle\Concern\InteractsWithPageBuilderContent;
use NRamos\CelebrimborBundle\Contract\HasPageBuilderContent;

#[ORM\Entity]
class Page implements HasPageBuilderContent
{
    use InteractsWithPageBuilderContent;

    // ... your own id, title, slug, etc.
}

Override pageBuilderFormat() to return PageBuilderFormat::Document if you store the full PageDocument instead of the default portable block list.

2. The form

use NRamos\CelebrimborBundle\Form\PageBuilderType;

$builder->add('document', PageBuilderType::class, [
    // 'format' => PageBuilderFormat::Document,
    'preview_url' => $this->generateUrl('admin_page_preview', ['id' => $page->getId()]),
]);

The field renders <my-page-builder> with the celebrimbor--page-builder Stimulus controller and transforms the document array ⇄ JSON automatically. The bundle auto-registers its form theme; if you disabled auto theming, add @Celebrimbor/form/celebrimbor_form_theme.html.twig to twig.form_themes.

3. The preview

A preview is just a controller calling the bundle. Two strategies:

use NRamos\CelebrimborBundle\Preview\AbstractPreviewController;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\Routing\Attribute\Route;

class PagePreviewController extends AbstractPreviewController
{
    #[Route('/admin/pages/{id}/preview', name: 'admin_page_preview')]
    public function __invoke(Page $page): Response
    {
        // A) Native Twig — one template per block (blocks/<name>.html.twig):
        return $this->renderPreview($page);

        // B) Same JS renderer as the editor (faithful to production):
        // return $this->renderJsPreview($page);
    }
}

For strategy A, create one template per block type under your configured prefix (default blocks/), e.g. templates/blocks/hero.html.twig:

<section class="hero">
    <h1>{{ title }}</h1>
    <p>{{ subtitle }}</p>
    {{ children }}
</section>

Each block template receives the block fields spread at top level, plus fields, settings, children (pre-rendered) and block.

For strategy B, override templates/bundles/CelebrimborBundle/preview/js_preview.html.twig to add an AssetMapper entry that calls mountCelebrimborPreview({ registry }).

Configuration

# config/packages/celebrimbor.yaml
celebrimbor:
    default_format: portable          # portable | document
    blocks_template_prefix: blocks    # <prefix>/<block>.html.twig
    render_missing_comment: false     # emit an HTML comment for unmapped blocks

License

MIT.