Study guide · Content elements and rich text editor
Building pages with content elements and the rich text editor
Content elements are the building blocks of every TYPO3 page: headers, text, images, videos, download lists and plugins. On this page you follow Lena, an editor at the Weidenau City Library. She is preparing the “Events” page for an author reading in March. She needs an announcement with a photo of the author, a video interview, the programme as a PDF and a list of further dates. Her colleague Tom is an integrator and looks after the technical side of the website. Afterwards you will know how to create and edit content elements and how to work confidently with the rich text editor.
Creating a new content element
You edit content almost always in the module Content > Layout. Up to TYPO3 13 the main module was called Web and this module was called Page. Lena selects the “Events” page in the page tree. On the right she sees the content areas of the page. Each area has a “+ Create new content” button. Clicking it opens the “New Page Content” wizard.
- Select the page in the page tree.
- Click “+ Create new content” in the area you want.
- In the wizard, choose a tab and then the element type.
- Fill in the form, for example the header and the text.
- Save and close.
The wizard sorts the types into tabs. Which tabs and types you see depends on the installation and on your permissions. Advanced editors or administrators often see more groups and types. If a type is missing for you, it is usually down to the permissions of your group.
The most important element types
The tab “Typical page content” holds the elements for ordinary pages. These include “Header Only” for a header on its own, “Regular Text Element” for text, “Text & Images”, “Text & Media” and “Images Only”. “Text & Media” is the most commonly used element. It combines a header, text and media such as images, videos or audio. Lena picks it for the announcement.
The tab “Lists” holds structured elements such as “Bullet List”, “Table” and “File Links”. File Links shows a list of linked files to download, for example PDFs. You choose the files from the Media module or upload them along the way. Lena uses File Links for the programme.
Other tabs are usually visible only to advanced users:
- “Form elements” holds the form and the login form for website users.
- “Menu” holds menus and lists of page links in various styles.
- “Plugins” holds plugins from installed extensions.
- “Special elements” holds “Plain HTML”, “Divider” and “Insert records”.
A Divider adds a horizontal rule. Plain HTML outputs HTML code that you type in yourself. TYPO3 outputs this code unchecked, and it bypasses the templates of the website. Broken markup can wreck the whole page. That is why Plain HTML is usually enabled only for experienced editors, and you should use it sparingly.
Insert records shows existing elements in another place without copying them. So it is a reference. The library has a teaser “Get your library card now” that should appear on ten pages. Tom creates it once, and on each page an Insert records element points to it. When Lena changes the text of the original, every reference changes too. Afterwards you may need to clear the cache of the affected pages.
Headers with meaning
Almost every element has the header fields at the top. In the Header field Lena types “Reading with Mara Lindqvist”. Below it is the select field Type. There you choose the heading level, that is, whether the header is a main heading, a subheading or an even lower level. The options are the default value, Layouts 1 to 5 and “Hidden”.
The level follows the meaning, not the design. Choose it so that the outline of the page is correct. A subheading inside the section “Programme” therefore gets a lower level than the section itself. Screen readers and search engines read the structure of the page from these levels. How big or colourful a header looks is decided by the design of the website. If you pick a level just for its font size, the structure is no longer right.
The setting “Hidden” hides only the header in the frontend. The element itself stays visible. In the backend the header remains as a title, so you can still recognise the element in the Layout module.
Editing, saving and changing the type
You open an existing element with the pencil icon on the element. Since TYPO3 14.2 the form opens by default in a side panel in the Layout module. The page stays visible in the background. At the top of the panel you see the title of the element and the buttons to save and close. “Expand” switches to the full form. If you do not like the panel, you can turn it off in the user settings with the option “Use quick editing for records in the Layout module”.
In the form you can change everything you have permissions for. Some fields are visible only to advanced editors or administrators.
TYPO3 does not save automatically. You have to click Save yourself. If you leave a changed form through the backend, TYPO3 asks whether you want to save. But if you close the browser window or use the browser's back button, there is no prompt. Your changes are then lost.
Sometimes an element cannot be saved. There are two typical causes:
- A required field is empty.
- A field contains an invalid value, for example letters in a number field.
If that field is on a different tab, you will not notice it right away. So check all the tabs.
You can also change the type of an existing element. To do this, you choose a different element type in the “Type” field at the top of the form. Because the new type has different fields, the form reloads after a confirmation prompt. Nothing is lost in the process. The previous content stays saved in the background.
Lena saves without an error message, but the frontend still shows the old version. There are several possible reasons:
- The browser cache is still showing the old version.
- The TYPO3 page cache is still delivering the old page.
- The change was not saved after all because of an error.
- The website uses workspaces. Then the change only goes live after it has been published.
If clearing the cache does not help, ask your administrator.
Hiding, moving, copying and recovering
You hide an element that is not finished yet or that you will need again later. There is a button for hiding on the element. You can do the same in the “Access” tab of the form and in the context menu. A hidden element is kept, but it does not appear in the frontend. The same button makes it visible again. Deleting its text would be the wrong way to go.
To move an element, drag it with the mouse into one of the highlighted areas of the page. If you drop it on a page in the page tree, it moves to that page. If you hold the Ctrl key while dragging, you create a copy instead. On a Mac you use the Alt key for this. You can also copy through the context menu: copy, then paste at the target position.
Copies are hidden by default. This way a copy does not appear on the website by accident. If the target page already has an element with the same header, TYPO3 also appends “(copy 1)”, with a higher number for further copies. This happens, for example, when you copy on the same page. You activate it on purpose once it is ready. Integrators can switch this behaviour off.
If Lena deletes an element by mistake, there are two ways back. The module Content > Recycler restores deleted elements and even whole pages. For that, the Recycler must be installed and she needs the permissions. If she has no access, the page history helps. In the context menu of the page in the page tree she chooses “History/Undo”. There she sees every change with its differences and can undo it, including a deletion.
Two people cannot sensibly work on the same element at the same time. If Lena opens an element that Tom is currently editing, TYPO3 shows a warning. It names the user and how long ago they started editing. TYPO3 never merges changes. Whoever saves last overwrites the other person's changes.
Adding and adjusting images
Elements such as “Text & Images”, “Text & Media” and “Images Only” have an “Images” or “Media” tab. In the “Images” tab Lena clicks “Add image”. A file selector window opens. Lena picks a folder in the folder tree on the left and the photo of the author in it. Next time the window opens the folder she used last. The search field finds files by name, including in subfolders. She can also upload a new image there.
The key point: The file lives in the Media module. The content element only holds a usage of that file. That is why you can move files to other folders in Media without changing the website. A file that is still used somewhere, however, cannot be deleted.
Below the thumbnail, a small arrow expands the metadata, including description, alternative text and link. These values come from the metadata of the file in Media. So you do not have to enter them again in every element. In the element you can override them for this one place. The metadata of the file stays unchanged and still applies to all other usages.
Two fields are easily confused:
- The alternative text replaces the image when it cannot be seen, for example for screen readers. It is usually invisible and has to convey the information of the image.
- The description is visible to everyone. It usually appears below the image and adds extra information.
With the image cropper you crop an image for this element. Depending on the configuration there are fixed aspect ratios, for example for different devices. The crop applies only to this usage. The original in Media stays unchanged, and TYPO3 does not create a new file for it. Other elements keep showing the whole image or their own crop.
Further sections follow below the image:
- “Media Adjustments” holds width and height in pixels and a border. These fields are optional. If you leave them empty, TYPO3 calculates the size itself. Some site packages, such as the Bootstrap Package, hide these fields and resize the images anyway.
- In “Gallery Settings” you decide where the images sit in relation to the text. TYPO3 arranges several images in columns by default, two side by side. You change this with “Number of Columns”.
- Under “Media Behavior”, “Enlarge on Click” turns on a larger view. A click then shows the image enlarged. Without further settings it opens in a separate window, and many websites show it in a lightbox. The original stays unchanged.
Embedding videos
For videos and audio you use “Text & Media”. It can do more than “Text & Images”, which only shows still images. The “Media” tab has two buttons:
- “Add media file” adds an uploaded file from Media or uploads a new one.
- “Add media by URL” embeds a video from a platform such as YouTube or Vimeo. You simply paste the address of the video.
Below the selector you see the allowed file extensions and platforms. Which ones are available depends on the configuration and on installed extensions. With “Autoplay” a video starts as soon as the page loads.
Lena wants to upload the interview herself, but the upload fails. The maximum upload size is limited for security reasons. In that case she asks the administrator to upload the video. Or she puts it on a video platform and embeds it from there.
With external platforms, data protection matters. An embedded YouTube video can send data to third parties as soon as the page loads. This can touch on data protection laws. So ask your data protection officer or legal department. Often you need a solution that asks for consent before loading, a so-called two-click solution. The video then only loads once visitors agree. The integrator installs such solutions as an extension.
The rich text editor
The text field in “Text & Media” is a rich text editor, RTE for short. It edits formatted text with markup such as bold, lists, headings and links. Using it feels much like a word processor. In TYPO3 14 the RTE is CKEditor 5. The system extension rte_ckeditor integrates it.
A short history: before TYPO3 8 the default editor was HtmlArea. With TYPO3 8, CKEditor 4 became the default, and TYPO3 12 switched to CKEditor 5.
Which buttons the toolbar shows is set by the configuration of the installation. TYPO3 ships the presets minimal, default and full. Integrators can create their own. That is why the editor does not look the same everywhere. Among other things, the default preset offers bold and italic, bulleted and numbered lists, links, tables, special characters and a button that removes formatting.
In the “Heading” menu the default preset offers Paragraph, Heading 2, Heading 3 and pre-formatted text. Heading 1 is left out on purpose. The main heading comes from the header of the element or of the page.
Some markup carries meaning, other markup only changes the look. Strong, shown as bold, marks important passages. Emphasis, shown as italic, marks stress. Screen readers and search engines evaluate both. A red font colour or large text inside a paragraph, on the other hand, carries no meaning. For headings you use real heading levels.
Shortcuts save time. On Windows, Ctrl + B makes the selected text bold and Ctrl + I makes it italic. On a Mac you use Cmd instead of Ctrl.
Lena copies the publisher's press release from a word processor. It brings along foreign fonts and styles. The editor already cleans up a lot when pasting. For any remaining formatting she selects the text and clicks “Remove Format”. Then she formats it with the styles of the website.
Two characters are normally invisible. The RTE highlights them in colour while you edit, so you can see where they are:
- A non-breaking space keeps two words together on the same line. Between “10” and “kg” the line will then never break. On Windows and Linux you insert it with Ctrl + Shift + Space.
- A soft hyphen marks a possible break point inside a word. A hyphen only appears if the word would not otherwise fit on the line. The shortcut is Ctrl + Shift + Minus, and there is also a button for it.
On a Mac you use Alt instead of Ctrl for both characters. You only see the colour highlighting in the backend. On the website the characters only affect line breaks.
Setting and removing links
To create a link, select the text and click the link icon. It is faster with Ctrl + K, or Cmd + K on a Mac. But the shortcut only opens the link dialog when the cursor is inside the editor. Outside the editor, the same combination opens the backend's live search.
The Link Browser appears. Its tabs show where a link can lead:
- To a page of the website, in the “Page” tab.
- To a file or a folder, for example a PDF.
- To an external URL, in the “External URL” tab.
- To an email address or a phone number.
In the “Page” tab you choose the page in the page tree. There you can also pick a content element on that page directly. TYPO3 then creates a link with an anchor, that is, with a hash sign and the number of the element. When clicked, the browser jumps straight to that element. This is how Lena links from the announcement to the section “Directions” on the “Contact” page.
- In the Link Browser, open the “External URL” tab.
- Enter the address in the “URL” field.
- If needed, choose “New window” under “Target”.
- Click “Set Link” to set the link and close the window.
To remove a link, put the cursor anywhere in the linked text. A small popover appears with the button “Unlink”. One click removes the link, and the text stays.
Extensions and plugins
Extensions add features to a TYPO3 installation, such as news, event calendars or forms. Many core features are system extensions themselves, for example forms, redirects or the dashboard. Extensions are installed, configured and updated by the integrator or administrator, not by editors. At the library, Tom takes care of this.
Many extensions bring a plugin. A plugin is a content element that outputs content from an extension in the frontend. You insert it like any other element. In the wizard you find plugins in the “Plugins” tab. This tab only exists if an installed extension offers a plugin there and you have the permissions for it. If it is missing, it is for one of these two reasons. Then the integrator can help.
After inserting a plugin, you configure it in the “Plugin” tab of the element. For a form you choose the form definition there. For the login form you choose, for example, the User Storage Page, that is, the folder with the website users.
The forms themselves are built in the module Content > Forms. Integrators often prepare them there in advance, for example a contact form. Lena then inserts the element “Form” from the “Form elements” tab and chooses the matching form definition in the “Plugin” tab.
Which settings a plugin has is explained in the manual of the extension that provides it. Many extensions publish their documentation on docs.typo3.org.
Key points
- You create new elements in Content > Layout with “+ Create new content”. The wizard only shows types you have permissions for.
- “Text & Media” is the most commonly used element. File Links is under Lists, while Plain HTML, Divider and Insert records are under Special elements.
- Insert records points to an original, while a copy is a separate element. Copies start out hidden, and with the same header on the target page they carry “(copy 1)” in their title.
- The heading level follows the meaning. “Hidden” hides only the header in the frontend.
- TYPO3 does not save automatically. An empty required field or an invalid value prevents saving. Changing the type does not delete content.
- When two people edit at once, TYPO3 warns you, and whoever saves last wins. You recover deleted content with the Recycler or “History/Undo”.
- Metadata and crops apply per usage, and the file in Media stays unchanged. By default, several images sit two side by side.
- Videos come in through “Add media file” or “Add media by URL”. With YouTube, think of data protection and consent.
- The RTE is CKEditor 5. Its buttons depend on the preset.
- Ctrl + K sets a link inside the editor, and “Unlink” in the popover removes it. The Link Browser knows pages, elements, files, folders, URLs, email and phone.
- The integrator installs extensions. You configure plugins in the “Plugin” tab, and help is in the extension's manual.
Terms
- Insert records
- An element that shows existing elements without copying them.
- Heading level
- The rank of a heading in the outline of the page, independent of its look.
- Metadata
- Information about a file, such as alternative text and description, which you can override per element.
- Alternative text
- A text version that replaces the image when it cannot be seen.
- Rich text editor
- An editor for formatted text, in TYPO3 14 this is CKEditor 5.
- Preset
- A saved configuration of the rich text editor, such as minimal, default or full.
- Link Browser
- The window in which you choose the target of a link.
- Non-breaking space
- A space at which the line never breaks.
- Soft hyphen
- A possible break point that only shows a hyphen when needed.
- Plugin
- A content element that outputs content from an extension in the frontend.