Vision and Architectural Principles

[Kanti]

The Vision

The vision for the Visual Editor is a form of content editing in which editors can modify the website directly in its actual visual presentation.

The Visual Editor does not display a simplified preview, an approximate backend representation, or a second version of the frontend. It uses the project’s real frontend rendering. While editing, the page looks exactly as it does to visitors, with only the necessary editor controls added.

This is genuine visual WYSIWYG editing:

Editors do not modify an abstract representation of the website. They edit the website directly in its actual visual presentation.

This concept is based on two equally important principles:

1. The editing experience uses the real frontend.
2. Integration is implemented as progressive enhancement, requiring as little effort as possible for existing projects.

These two principles depend on each other. A Visual Editor can only achieve broad adoption if it does not require a second frontend architecture and if existing projects do not need to be fundamentally rebuilt.

One Representation Instead of Two Rendering Systems

Many visual editors attempt to recreate the frontend within a separate editor interface. This results in two representations:

• the real frontend
• a separate editing or preview representation

As soon as two rendering systems exist, they can diverge from one another. Templates, CSS, JavaScript, breakpoints, and project-specific components must then be considered twice. Every further development of the frontend may require additional adjustments to the editor.

The Visual Editor deliberately takes a different approach. It edits the server-side rendered website itself.

The regular Fluid rendering, frontend CSS, and project-specific JavaScript remain the foundation of the presentation. There are no separate Visual Editor templates and no additional stylesheet that attempts to recreate the frontend inside the editor.

This principle is explicitly understood as inline editing that matches the frontend output. Fluid ViewHelpers are used to identify editable text and content areas within the regular rendering. In general, project-specific CSS and JavaScript should continue to work. Individual adjustments may nevertheless be required when the behaviour of a component conflicts with editing mode. This does not change the underlying principle: the Visual Editor does not reconstruct the project. Instead, the existing project is enhanced with editing capabilities.

What “Exactly Like the Frontend” Means

“Exactly like the frontend” means that the visible presentation is identical. The only exceptions are a small number of controls such as selection outlines, action bars, drag handles, or indicators for editable fields.

However, it does not mean that every conceivable state of a website is displayed simultaneously.

A website may depend on factors such as:

• viewport size
• active language
• workspace
• preview time
• backend and frontend user permissions
• logged-in frontend users
• personalisation
• external or time-dependent data

In the long term, the Visual Editor should make these states selectable through “View Options”. The presentation remains correct for the selected state. However, it does not attempt to display all possible variants simultaneously within a single view.

Responsive editing follows the same principle. The Visual Editor does not simulate a separate responsive layout. Instead, it displays the real frontend at the selected viewport size. The available viewport sizes should be configurable for each project. Automatically deriving them from the CSS may be added later, but it is not a necessary part of the fundamental concept.

Direct Editing Instead of a Form Next to the Page

The Visual Editor does not merely display a form next to the frontend and transfer its changes into a preview.

Such a solution may reduce the distance between the form and the output, but it still follows a form-oriented editing model. The editor must continue switching between the input field and the location where the result appears.

True visual editing begins when the content and the input location are identical.

A heading or paragraph is edited directly at its actual position. An image is selected and cropped where it appears within the layout.

This corresponds to the behaviour of modern document applications. In a word processor, a paragraph is not edited in a separate form next to the document either.

Progressive Enhancement Instead of Rebuilding the Project

The Visual Editor is neither an alternative rendering system nor a new project architecture. It enhances existing TYPO3 projects incrementally.

The smallest possible integration consists of making content elements accessible through an action bar. This already provides actions such as editing, hiding, deleting, and creating elements. Existing image editing functionality can also be used.

Inline editing can then be added selectively for individual fields. A project may initially make only headings editable and later integrate additional text fields or content areas.

Content that has not been marked remains part of the normal frontend. It is neither broken nor incomplete. The integrator deliberately decides which visible fields can be edited directly.

Outside editing mode, the frontend output must not change. Core ViewHelpers must also render the frontend normally when the Visual Editor is not installed. This makes it possible to disable or remove the Visual Editor without having to revert every template.

Exceptions include extension-specific helpers such as f:mark.contentArea or f:editMode. These primarily support migration, compatibility with older TYPO3 versions, and specific use cases. The long-term objective is to cover as many integration points as possible through generally useful Core abstractions.

Explicit Integration Instead of Automatic DOM Detection

The Visual Editor does not attempt to infer which elements might be editable by analysing arbitrary HTML.

Automatic detection cannot reliably determine:

• which TYPO3 record a DOM node originates from
• which field is being displayed
• whether a visible value was stored directly or calculated
• whether multiple fields were combined into a single output
• whether the output originates from a TCA-based record at all
• which editing permissions apply to the field

Retrospective analysis or manipulation of the DOM would be error-prone, difficult to control, and potentially expensive. With complex templates, it would inevitably create incorrect mappings.

Explicit integration within the Fluid template, by contrast, establishes a clear connection between the presentation, the record, and the field. The integrator retains control over which content is editable. At the same time, the required effort remains low because existing output does not need to be rebuilt. Instead, it is replaced with more appropriate rendering abstractions.

The objective is not to burden integrators with Visual Editor-specific knowledge. On the contrary, templates should describe regular, semantically correct TYPO3 rendering. Editability should emerge from this as automatically as possible.

Why f:render.text Is Necessary

Before f:render.text, text fields were rendered differently depending on their configuration:

• simple output for plain text
• f:format.nl2br for multiline text
• f:format.html for rich text

This may work for presentation alone. For reliable visual editing, however, essential information is missing.

A formatter usually receives only the final value. It does not know:

• which record the value belongs to
• which table it originates from
• the UID of the record
• which database field is being rendered
• how the field is configured in TCA

Without this information, the Visual Editor cannot safely associate the visible content with an editable TYPO3 field.

For this reason, f:render.text receives the complete record and the field name. This allows the ViewHelper to evaluate the TCA configuration and determine whether the field should be rendered as plain text, multiline text, or rich text.

f:render.text is a record-aware ViewHelper that renders text fields according to their TCA configuration and removes manual formatting logic from templates. The ViewHelper originated from the need to create an unambiguous integration point for the Visual Editor. At the same time, it has evolved into a generally better rendering abstraction.

A template should not need to know whether a field currently contains plain text, multiline text, or rich text. That decision has already been made in TCA. The template should not have to duplicate it.

This is also why there is no additional f:render.richText ViewHelper. An earlier separation would have forced the integrator to make an unnecessary decision. With f:render.text, the TCA configuration of a field can be changed without subsequently having to update every template.

The ViewHelper therefore improves more than just Visual Editor integration. It also reduces duplicated configuration and makes templates more robust.

Errors Should Remain Visible

If a template accesses a field that does not exist, f:render.text throws an exception by default.

This is a deliberate decision. An incorrect assumption in a template should become visible during development instead of silently producing empty output.

For shared partials that need to support records with different fields, an optional setting is available. In this case, the ViewHelper can return null in a controlled manner. This distinguishes between two situations:

• An unexpectedly missing field is an error.
• A deliberately optional field is part of the template concept.

No Visual Editor-Specific Templates

The integration deliberately avoids using a ViewHelper such as ve:editableText as the regular rendering method.

Such a ViewHelper would couple the templates directly to the extension. After uninstalling the extension, the templates would need to be modified again. It would also unnecessarily mix the question of editability with the responsibility of rendering.

Instead, f:render.text describes how a TCA-based text field should be rendered correctly. The Visual Editor can integrate itself into this generally valid rendering point when it is installed and active.

Normal TYPO3 rendering remains the default case. Editability is an additional capability.

This principle also applies to Fluid Components. A reusable component should ideally know nothing about the underlying record, TCA, or the Visual Editor. The caller renders the value and passes a string or Stringable object to the component. This keeps the component independent and reusable.

The same applies to f:render.contentArea. To edit content directly and move it using drag and drop, identifying individual text fields is not sufficient. The structural meaning of content areas must also be known.

Historically, TYPO3 content has often been rendered through freely configurable constructs such as f:cObject, lib.dynamicContent, or manual loops. Although this is flexible for output generation, other systems cannot recognise that a particular location represents a defined content area.

f:render.contentArea introduces a typed and identifiable entry point. The official TYPO3 documentation recommends the ViewHelper instead of manual f:cObject or f:for constructs. It renders a content area provided by the page-content Data Processor and allows extensions to modify the output through events.

For the Visual Editor, this entry point provides exactly the structural context required to create, move, and assign content elements.

f:mark.contentArea was a necessary fallback for TYPO3 13 and for existing rendering methods. After a migration period, this transitional solution should eventually be removed. Wherever markers are still required today, it should be examined whether the underlying rendering API can be extended so that f:render.contentArea can be used directly.

Existing TYPO3 Mechanisms Instead of Separate Subsystems

One of the most important architectural principles is:

The Visual Editor should avoid rebuilding anything TYPO3 already provides.

Content elements remain TYPO3 records. Content areas remain TYPO3 content areas. Positions, columns, parent relationships, and other structural information remain part of the existing TYPO3 data model.

The Visual Editor makes these structures visually accessible, but it does not redefine them.

The same applies to the rich-text editor. The Visual Editor does not implement its own RTE. Instead, it uses the existing TYPO3 and CKEditor integration. This preserves the RTE configuration already defined for a field. It also results in less additional code and prevents projects from having to maintain their editor configuration twice.

Changes are not written directly to the database through a separate persistence layer either. They are always processed through TYPO3’s DataHandler.

The DataHandler processes changes to TCA-configured tables, evaluates write permissions, and considers aspects such as versioning, history, logging, and relations. The client is fundamentally treated as untrusted. The record, field name, and value must be validated on the server.

The interface displays only fields for which the user has the necessary permissions. Final enforcement nevertheless takes place on the server and within the DataHandler.

A Page Builder in Its Interaction Model, but Technically Not Quite One

From the editor’s perspective, the Visual Editor provides typical page-builder functionality:

• Elements can be created.
• Elements can be moved or copied.
• Content can be edited directly.
• The resulting page is visible immediately.

Technically, however, the Visual Editor does not introduce its own page-builder model.

It has neither its own grid engine nor its own layout definition. Multi-column containers and complex structures continue to be provided by the responsible TYPO3 mechanisms, such as the Container extension.

The Visual Editor should make such elements visually operable, but it should not become dependent on a particular third-party extension or recreate that extension’s functionality in a second implementation.

If TYPO3 gains Core functionality for containers, grids, or dynamic layouts in the future, the Visual Editor can make those features visually accessible. The functional definition of those structures should not, however, become part of the Visual Editor itself.

Therefore:

In its interaction model, the Visual Editor is a page builder. In its technical architecture, it is a visual user interface for existing TYPO3 structures.

Deliberate Boundaries

The Visual Editor is not intended to replace the TYPO3 backend completely.

In particular, the following are not core objectives:

• unrestricted visual design
• arbitrary CSS manipulation
• defining new content types
• complete page and record configuration
• replacing all backend modules and specialised forms

Not every TCA field should automatically become editable in the frontend. In principle, only content that is visibly rendered and clearly integrated can be edited. A field that is not part of the visible presentation does not automatically belong in a WYSIWYG interface.

Calculated or heavily transformed output must also be handled clearly. TypoLinks, for example, are not necessarily directly editable inline. If the visible link text originates from a separate text field, that field can be edited. The link configuration itself may continue to be managed through a regular TYPO3 form, which is usually directly accessible from the Visual Editor.

Rich text is supported as long as it is rendered through the regular TYPO3 mechanisms. Custom lib.parseFunc_RTE configurations may nevertheless introduce additional limitations.

Visual transformations, such as truncating text after a particular length, should preferably be implemented through CSS so that the stored content and the edited content remain identical.

Saving as a Deliberate Action

Changes do not need to be permanently saved after every input.

Particularly within the Live Workspace, editors should be able to prepare several changes and save them together once the desired result has been reached. This keeps the editor in control of when changes are actually applied.

An “Autosave” feature may be provided in suitable workspace configurations. However, it is not a universal principle that must always be active regardless of the working context.

What matters is that even a modern visual interface respects TYPO3’s existing processes for workspaces, permissions, and publishing.

Technical Limitations Are Not Architectural Principles

Some current limitations result from the present technical environment rather than from the long-term vision.

Headless and non-Fluid projects are not currently first-class integration targets because the implementation relies heavily on Fluid ViewHelpers and server-side rendered HTML.

The current project documentation explicitly states that a public API is required for robust headless integration. In the long term, alternative rendering methods should be connectable through a suitable PHP API. However, it must first be determined how they can reliably provide the necessary information about records, fields, and content areas.

Server-side rendered HTML and the use of the same templates for editing and the frontend remain core principles. Introducing separate editing templates would cause the Visual Editor to abandon one of its central promises.

Same-origin and multi-domain restrictions are also technical limitations rather than desired product characteristics. They arise from factors including authentication, frame communication, and current Core APIs. They should be improved over time without changing the fundamental concept.

Summary of the Architectural Principles

The Visual Editor follows these principles:

1. There is only one frontend rendering system.
2. Editing takes place directly on the actually rendered website.
3. Outside editing mode, the frontend output remains unchanged.
4. Integration is incremental and follows the principle of progressive enhancement.
5. Templates describe correct TYPO3 rendering, not a special editor configuration.
6. Records and fields are associated explicitly and reliably.
7. TCA is the central source of truth for the meaning and presentation of fields.
8. Existing TYPO3 Core mechanisms are reused.
9. The Visual Editor does not introduce a parallel content, layout, or persistence model.
10. Technical limitations are clearly distinguished from permanent architectural principles.

The Visual Editor is therefore not a second system alongside TYPO3. Instead, it provides a new visual interaction layer for the existing system.

Its strength does not come from rebuilding as many TYPO3 features as possible. Its strength lies in making existing functionality accessible where editors actually see the result: directly within the rendered frontend.