typo3-visual-editor

What this skill does

# TYPO3 Visual Editor

> Source: https://github.com/dirnbauer/webconsulting-skills

Use this skill to make a TYPO3 project ready for `friendsoftypo3/visual-editor`, especially when upgrading Fluid templates so editors can edit fields and content areas in context.

The critical work is not only installing the extension. The Visual Editor needs frontend output that is traceable back to records, fields, and content areas. Migrate page columns to `f:render.contentArea` where possible and migrate editable text fields to `f:render.text`.

## What it does

The Visual Editor adds an in-backend frontend editing mode for TYPO3 content. Editors can work close to the rendered page, with inline text editing, drag-and-drop repositioning, adding/removing content elements, real-time preview behavior, workspace support, optional autosaving, container support, and Context Panel integration.

For custom sitepackages, the extension depends on Fluid hooks:

- `f:render.text` marks TCA-backed text fields as editable and renders them according to field configuration.
- `f:render.contentArea` renders TYPO3 v14.2+ page content areas and lets extensions modify content-area output.
- `f:mark.contentArea` is the Visual Editor fallback for TYPO3 v13 or legacy renderers that cannot yet use `f:render.contentArea`.

## When to use

Use this skill when the user asks for:

- installing or removing `friendsoftypo3/visual-editor`
- making a sitepackage compatible with visual editing
- replacing `f:cObject typoscriptObjectPath="lib.dynamicContent"` column rendering
- updating Fluid templates for fields shown in the backend
- using `f:render.text`, `f:render.contentArea`, or `f:mark.contentArea`
- diagnosing why inline editing, drag-and-drop, add, delete, or content-area highlighting does not work
- upgrading TYPO3 v13/v14 templates toward v14.2+ PAGEVIEW rendering

## Version strategy

Prefer TYPO3 v14.2+ and Core ViewHelpers:

```html
<f:render.contentArea contentArea="{content.main}" />
<h1>{record -> f:render.text(field: 'header')}</h1>
```

Use `f:mark.contentArea` only when the project cannot use the v14.2+ content-area pipeline yet, for example TYPO3 v13 compatibility or legacy content rendering with VHS/Flux/container loops.

Always verify the package constraints before changing `composer.json`; current upstream requires PHP 8.2+ and supports TYPO3 13.4.22+ or 14.2+.

## How to install

Composer installation:

```bash
ddev composer require friendsoftypo3/visual-editor
ddev typo3 cache:flush
```

Without DDEV:

```bash
composer require friendsoftypo3/visual-editor
vendor/bin/typo3 cache:flush
```

Non-Composer installation:

1. Install the extension through the TYPO3 Extension Manager.
2. Activate `visual_editor`.
3. Flush TYPO3 caches.
4. Run database updates if the Install Tool requests them.

Optional helpers:

- Install `andersundsehr/visual_editor_fluid_styled_content_addon` if the project relies heavily on `fluid_styled_content` templates and wants automatic text-editing integration there.
- Consider `wapplersystems/multisite-belogin` for multi-domain projects where backend users need to be logged in across several frontend domains.

## How to configure

1. Confirm backend users can access the Visual Editor module and page tree.
2. Make frontend rendering use templates that expose editable records and fields.
3. Add `record-transformation` where templates currently receive raw arrays but need Record objects.
4. Render page columns through `f:render.contentArea` on TYPO3 v14.2+.
5. Wrap unavoidable legacy column renderers with `f:mark.contentArea`.
6. Ensure rich-text styles used by CKEditor are also available in frontend CSS, because Visual Editor uses the rendered frontend context.
7. Test in the backend Visual Editor module with a real editor user, not only an admin account.

### Record transformation

If a content element template has raw `{data}` but no `{record}` object, add the data processor before using `f:render.text`:

```typoscript
lib.contentElement.dataProcessing.1768551979 = record-transformation
```

Then render TCA-backed text fields from the Record object:

```html
<h1>{record -> f:render.text(field: 'header')}</h1>
```

Use the database/TCA field name in `field`, not an Extbase property alias.

## Template migration workflow

### 1. Inventory editable fields

Search Fluid templates for direct field output and manual text formatting:

```bash
rg -n "\{(record|data)\.[a-zA-Z0-9_]+\}|format\.html|format\.nl2br" Resources/Private
```

For each TCA-backed input, textarea, or richtext field shown in frontend output, prefer `f:render.text`.

Before:

```html
<h1>{record.header}</h1>
<f:format.html>{record.bodytext}</f:format.html>
<f:format.nl2br>{record.teaser}</f:format.nl2br>
```

After:

```html
<h1>{record -> f:render.text(field: 'header')}</h1>
<div class="prose">{record -> f:render.text(field: 'bodytext')}</div>
<p>{record -> f:render.text(field: 'teaser')}</p>
```

For conditional rendering, render once into a variable so the condition and output use the same processed value:

```html
<f:variable name="header" value="{record -> f:render.text(field: 'header', optional: true)}" />
<f:if condition="{header}">
    <h1>{header}</h1>
</f:if>
```

### 2. Migrate content areas

Find legacy content rendering:

```bash
rg -n "lib\.dynamicContent|f:cObject|v:content\.render|flux:content\.render|children_" Resources/Private Configuration
```

On TYPO3 v14.2+, replace dynamic `colPos` rendering with `f:render.contentArea`.

Before:

```html
<f:cObject typoscriptObjectPath="lib.dynamicContent" data="{colPos: '3'}"/>
```

After:

```html
<f:render.contentArea contentArea="{content.main}" />
```

The replacement is not a mechanical `3` to `main` conversion. `{content.main}` exists when the page uses `PAGEVIEW`, the `page-content` data processor, and a backend layout column whose identifier is `main`. Map every old `colPos` to the matching backend layout identifier:

| Legacy value | Backend layout contract | Fluid output |
|--------------|-------------------------|--------------|
| `colPos = 0` | identifier `main` | `{content.main}` |
| `colPos = 1` | identifier `sidebar` | `{content.sidebar}` |
| `colPos = 3` | identifier `main`, `stage`, or project-specific name | `{content.<identifier>}` |

Set up PAGEVIEW and page-content processing when missing:

```typoscript
page = PAGE
page {
  10 = PAGEVIEW
  10 {
    paths.10 = EXT:my_sitepackage/Resources/Private/Templates/
    dataProcessing.10 = page-content
  }
}
```

Keep backend layout identifiers stable because they become the template contract.

### 3. Use fallback wrappers for legacy rendering

If the project cannot use `f:render.contentArea`, preserve the existing renderer and wrap it:

```html
<f:mark.contentArea colPos="3">
    <f:cObject typoscriptObjectPath="lib.dynamicContent" data="{colPos: '3'}"/>
</f:mark.contentArea>
```

For EXT:container child columns:

```html
<f:mark.contentArea colPos="201" txContainerParent="{record.uid}">
    <f:for each="{children_201}" as="element">
        {element.renderedContent -> f:format.raw()}
    </f:for>
</f:mark.contentArea>
```

For EXT:vhs:

```html
<f:mark.contentArea colPos="0">
    <v:content.render column="0"/>
</f:mark.contentArea>
```

For EXT:flux:

```html
<f:mark.contentArea colPos="{data.uid}00">
    <flux:content.render area="column0"/>
</f:mark.contentArea>
```

Treat `f:mark.contentArea` as a compatibility step. Plan to remove it when the project moves fully to TYPO3 v14.2+ Core content areas.

## Backend fields

For every field that is editable in the backend and rendered in the frontend:

- Use `f:render.text` for TCA `input` and `text` fields, including rich text.
- Use the exact database field name, for example `header`, `subheader`, `bodytext`, or `tx_sitepackage_teaser`.
- Use `optional: true` only for shared partials where the field may legitimately be absent.
- Do not use `f:render.text` for computed values, virtual getters, FAL objects, links, boole