The Elegant Efficiency of TYPO3 Overlays

Overlays are used in two key features of TYPO3: 

• Localization of data. Localization in its simplest form is a 1:1 translation of every bit of content you have on your website.
• Content staging of data (“Workspaces”). Workspaces is a mechanism to add or modify content, preview, and have a defined publishing workflow before your visitors see new content on your website.

Internally, a new record, uid=14, is created, referencing uid=13 as the “Translation Parent” (typically a field called “l10n_parent”), which is the “Default Language” record.

Here’s where we see overlays come into action. TYPO3 uses overlays under the hood when previewing a page with content in a translation or in a workspace (or both).

For this to work, TYPO3 has a “Context” object, where the current workspace (ID) and the language (ID) is stored. TYPO3 first always fetches the “Default Language of the Live Record” (language=0 and workspace=0). For each and every record, it then checks if there is a Versioned Record of this “Default Language” (by searching for a record with “t3ver_oid=13” and “t3ver_wsid=1”), and replaces all information of this record with the versioned record. However, it keeps the actual “uid”.

The technical elegance of overlays: By keeping the “uid” in place, any reference or link to this content will still connect to the “live version”, so TYPO3 does not need to replace and adapt all links when a versioned record is created.

If the TYPO3 editor requests the Hebrew translation, TYPO3 then checks for a “language overlay”, checking for a record in the “Live Version” with its “Translation Parent” set to the uid=13 (the live default language). If in the staging workspace, the Hebrew version is also checked for a Versioned Record.

• Default content
  • Localized Hebrew content

• Default content
  • Versioned record
    • Localized Hebrew content
      • Versioned record of localized record

TYPO3 does all of this under the hood. Using the TYPO3 Core API for reading (PageRepository) and writing (DataHandler) handles all of that for you!

This is one of the main reasons why the concept of a “Default Language” and its connection to that exists. In addition, this allows for one further feature of TYPO3: Fallbacks.

The so-called “Fallback Modes” when configuring a site language are now put into place:

• Strict Mode: If no French translation is found, do not even think of showing the default language. The non-translated content is just not shown.
• Fallback Mode: If no French translation is found, show the English version.
• Free mode: Do not query the default language (= do not use the overlay technology). This is useful when your language is not bound to the default language.

In addition, I coined the term “Floating Records“—records within a translation that do not have an overlay can still be rendered. Imagine a teaser element on a page that should only be shown in the Polish version—that’s a floating record. However, this record does not follow the sorting and ordering of the overlay mechanism.

Instead of cloning the full database for versioning, TYPO3 handles the versioned content automatically for you by just copying the modified content.

During the publishing process, TYPO3 keeps the “Live Version” in place and just swaps the modified fields into the existing live database records.

By now you should understand why TYPO3 is so powerful. Using TYPO3’s native APIs handles everything for you. If you are interested in looking at your project together, we can see if your project is utilizing TYPO3 APIs properly. Give us a shout.