Architecture 

Overview 

A reference is a regular new content element of type shortcut that points to the original record. paste_reference no longer bends the core copy operation into a reference. It creates the shortcut element through the core AjaxDataHandler and only adds its own controls to the backend.

The extension extends the page module instead of replacing it. The core paste buttons stay untouched, paste_reference places its own controls next to them and talks to the core through public core APIs and the markup of the page module.

How a reference is created 

Every action ends in a single write path: AjaxDataHandler.process(), which sends the request to the core route record_process.

• Paste as copy sends the core copy command.
• Paste as reference sends a datamap that creates a new shortcut element.

Example datamap for a reference (comments for explanation only):

{"data": {"tt_content": {"NEW6f3a": {
  "pid": -456,                 // negative: after element 456, positive: top of the column
  "CType": "shortcut",
  "records": "tt_content_123",
  "colPos": 1,
  "sys_language_uid": 0,       // always explicit, see "Language" below
  "tx_container_parent": 789,  // only with EXT:container
  "header": "Reference: Teaser home page"
}}}}

The DataHandler handles everything else as for any new content element:

• A negative pid inserts the record after the given element and takes over its page; a positive pid places it at the top of the column.
• authMode for CType and write access to the target page are checked by the DataHandler.
• In TYPO3 14.3 the column restriction is checked for CType shortcut (DataHandlerContentElementRestrictionHook), which is the correct rule for a reference.
• In a workspace the record is created as a workspace version of the current backend user.

No DataHandler hook and no request parameter are involved, so the behaviour is the same for every caller.

Components 

Behaviour details 

Integration points with the TYPO3 core 

Public core APIs used:

• DataHandler datamap and commands via the route record_process
• PSR-14 event ModifyPageLayoutContentEvent
• Context menu item providers with data-callback-module
• Element browser message typo3:elementBrowser:elementAdded
• previewRenderer in TCA
• Language labels as JavaScript modules ~labels/paste_reference.db (TYPO3 14.2 and later, Feature #108941)

Dependencies that are not guaranteed by the core:

• The core still describes AjaxDataHandler as "private API yet".
• The data attributes of the page module (data-colpos, data-language-uid, data-tx-container-parent) are stable in practice, but not documented as API.
• Hiding the core paste button relies on the internal class .t3js-paste-copy. If the core changes it, the worst case is two paste buttons side by side; core paste keeps working.

These are the places that will need attention when the core rebuilds paste and drag & drop in the page module (Deprecation #109529).

Differences between 6.x and 4.1 

The page module markup is identical in both versions, so the JavaScript logic (toolbar, command, record picker) is shared in substance. Both versions are maintained in separate branches, because a shared branch would need a version switch in five places, two of them in exactly the legacy paths 6.0 removes.

Design decisions 

No DataHandler hook

Up to 5.x a processCmdmap hook read reference=1 from the global request and re-entered the running DataHandler instance. This did not work reliably for CLI, workspace publishing or other AJAX paths and could overwrite the state of the running process. A datamap needs no hook at all.

Additive instead of replacing

5.x hijacked the core paste buttons via MutationObserver and shipped a fork of the core drag & drop module (about 1,660 lines of JavaScript). 6.0 places its own controls next to the core ones. If the extension fails, the core paste function keeps working.

Keep the "Copy / Reference" modal

Editors keep the familiar dialog. To avoid two paste buttons, the core button is hidden via CSS in copy mode.

No workspace cleanup

The former cleanupWorkspacesAfterFinalizing() ran after every tt_content command and is no longer needed, because the core creates workspace versions correctly.

No drag & drop as reference

The core drag & drop module allows no third action besides move and copy without replacing it. Drag & drop as reference is only possible once the core offers an extension point for drop actions.

Known limitations 

• After pasting, the page reloads. Other open backend views are not notified.
• The header is a snapshot and does not follow later changes of the original.
• Language label modules are cached by the browser. Clear the browser cache after an update if labels look outdated.
• The toolbar relies on the current page module markup and will need an update once the core rework of the page module (#109529) lands.

Outlook 

The core is rebuilding paste and drag & drop in the page module (Deprecation #109529). A core extension point for additional paste actions, for example a PSR-14 event that adds options to the paste modal, would reduce paste_reference to the datamap, the label and the preview. A proposal for such an extension point is planned as a Forge issue.