The Elegant Efficiency of TYPO3 Overlays

Introducing 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.

Setting the scene for overlays

Initial set-up: English only, live content

Let's start with a simple example: a website in English, with no translations, and no workspaces. A Content Element (record of type “tt_content”) displays on the website in the “Default Language” and as a “Live Record”. Within the database, this record has a “uid”, a numeric representation of the content which can be referenced or linked to. In our example, this record has the uid=13.

Adding a translation

Let's add a second language, for example “Hebrew”, to the site.

Next we update our content element by translating the content into Hebrew. This is the “Translated Language” and it is still a “Live Record” so the content is public as soon as we hit the Save button.

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.

Adding a Workspace to the mix

Let’s add a custom Workspace called “Staging Workspace”, so we can work on unpublished content without affecting the live website. Here, we’ll see all content of the current “Live Workspace” until something is changed. When changing something in the “Default Language”, a copy of this record is created with uid=15. This copy, which we call “Versioned Record”, resides in Workspace ID=1, and has a connection to its “Live Record” which is stored inside the database in a field called “t3ver_oid” (oid stands for Online ID).

We can now preview the modified (“Versioned”) content, and also change the translation as well. This way, we get another copy (which is uid=16), this time from the “Translated Language” of the “Live Record”, making it the “Versioned Record of the Translation Language”.

The mechanics and beauty of overlays

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.

A simplistic view of overlays looks like this:

• 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!

Benefits of the overlay mechanism

TYPO3 always queries the “Default Language” of the “Live Workspace” first.

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.

If no Language overlay can be found, you can decide what happens.

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.

For Workspaces, only modified or newly created records are duplicated.

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

Publishing a Workspace is just exchanging content.

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

Summary

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. Let’s connect!