TYPO3 Templates
Create and modify templates with TypoScript and TemplaVoila
- Build dynamic and powerful TYPO3 templates using TypoScript, TemplaVoila, and other core technologies.
- Customize dynamic menus, logos, and headers using tricks you won’t find in the official documentation.
- Build content elements and template extensions to overhaul and improve TYPO3’s default back-end editing experience.
- Follow along with the step-by-step instructions to build a site from scratch using all the lessons in the book in a practical example.
Updating the rich text editor
While we are making life easier for the editors, we can work on one of the areas they have to spend the most time in: the Rich Text Editor (RTE). The rich text editor allows anybody editing text or content in the TYPO3 backend to add formatting and styling such as bold or italics without using special syntax or HTML, and see the results in the text area immediately. This is also known as a WYSIWYG (What You See Is What You Get) editor and we’ve used it in the previous chapters to edit our own content:
Out of the box, TYPO3 comes with the htmlArea RTE (extension key: rtehtmlarea), and it really is a good editor to work with. The problem is that it’s configured by default to fit everybody, so it doesn’t really fit anybody particularly well without a little bit of modification: it has it’s own classes that we probably don’t actually use, toolbars that may give too many options, and it blocks some handy tags such as the embed and object tags that we need for embedded video. Luckily, the htmlArea RTE is very configurable like everything in TYPO3 and allows us to override or add to almost all of its rules.
There’s an entire TSref document (http://typo3.org/documentation/documentlibrary/extension-manuals/rtehtmlarea/current), so we’re not going to try to cover everything that is possible. The TSref is being updated with the new releases, so I recommend checking it out if you have any questions or want to get more information on configurations that we have only glossed over or skipped.
As a final note, some of the configuration properties in this section will work on other RTE options, but many are special for the htmlArea RTE. We are going to talk about the htmlArea RTE because it is already installed by default and has a lot of powerful options, but you may choose to install a different editor as an extension in the future. TYPO3 allows us to replace the RTE in the backend with TYPO3 extensions, and we might want to replace the default htmlArea RTE if we need to support older browsers or use special features like plugins for editing images. If you are using a different editor, you may need to look at its documentation for any differences in configuration.
Editing the TSconfig
Configuration of the RTE is done completely in the TSconfig for the user or the page. We’ve used the TypoScript template for frontend configuration and layout, but the TSconfig is mainly used for configuring backend modules in TYPO3 like the RTE. The rich text editor is a backend module, so we need to use the TSconfig to configure it for our editors.
The TSconfig can be modified through the Page properties view on any page in the Options tab (shown in the following screenshot):
Above you can see an example of the TSconfig with some of the modifications that we are going to look at for the RTE. Of course, you can edit the TSconfig on any page in the page tree that you would like, but we are going to be working on the Root page. Like templates, the TSconfig is inherited from the parent pages in the page tree, so we can modify all of the instances of the RTE in the entire site by modifying the Root page.
CSS properties
The first thing that we want to update in our editor is the CSS. Without special configuration, the htmlArea RTE uses its own default CSS to decide how the different options such as headings, bold, italics, and so on, look in the text area preview. We can update the TSconfig, to load our own external stylesheet for the RTE that more closely resembles our working frontend site; the editors will see the same basic styling for paragraphs and headings as the visitors and have a better idea of what their content will look like in the frontend.
According to the TSref on htmlArea, the following stylesheets are applied to the contents of the editing area by default in ascending order (we’ll talk about each one in a moment):
- The htmlarea-edited-content.css file from the current backend TYPO3 skin (contains selectors for use in the editor but not intended to be applied in the frontend)
- A CSS file generated from the mainStyleOverride and inlineStyle assignments
- Any CSS file specified by contentCSS property in the page TSConfig
We don’t need to worry about the first file, htmlarea-edited-content.css. The TYPO3 skin that styles everything in the backend controls it. By default, there is an extension named TYPO3 skin, and we can simply override any of the styles by using the contentCSS property that we will see in a minute.
The mainStyleOverride and inlineStyle properties are controlled by the htmlArea RTE, and TYPO3 generates a CSS file based on their settings in the extension. The mainStyleOverride contains all of the default text settings including sizes and font choices. If we are using our own CSS, we will want to ignore the original styles, so we are going to use the ignoreMainStyleOverride property in our TSconfig. To ignore set this property for our RTE, we can add the following line to the TSconfig on our main page:
RTE.default.ignoreMainStyleOverride = 1
The inlineStyle assignments in TYPO3 create default classes for use in the RTE. You’ve probably already noticed some of them as options in the style drop-downs in the editor (Frame with yellow background, Justify Center, Justify Right, and so on). If we override the inlineStyle assignments, the default classes are removed from the RTE. Of course, we don’t need to eliminate these classes just to use our own, but we can do this if we are trying to clean up the RTE for other editors or want to make our own alignment styles.
Finally, we can use the contentCSS property to load our own external stylesheet into the RTE. To use our own stylesheet, we will use the following code in the TSconfig to use a new stylesheet named rte.css in our editor:
RTE.default.contentCSS = fileadmin/templates/css/rte.css
At this point, we’re all pretty used to the syntax of TypoScript, but a review might be in order. In the previous line of TypoScript, we are updating the contentCSS property in the default instances of the RTE object with the new value fileadmin/templates/css/rte.css. If you understand that line, then everything else we’re about to cover will be easy to pick up.
As we want to use our own CSS file and override the defaults at once, this will be the TypoScript for our TSconfig:
RTE.default {
contentCSS = fileadmin/templates/css/rte.css
ignoreMainStyleOverride = 1
}
Of course, the next thing we need to do is create our new stylesheet. We don’t want to use the complete stylesheet that we are using for the frontend because it could be thousands of lines and will have a lot of formatting and page layout rules that we don’t need for simple text editing. Instead, we can just copy the most important text and paragraph styles from our style.css file in the fileadmin/templates/css/ directory into a new file called rte.css. In addition, we’re going to add two new classes to style.css and copy them over; we’ll create a class named blue to set the font color to pure blue and a class named red to set the font color to pure red. This should be the content of our new file, rte.css:
p, ul, div {
color: #666;
font-size: 12px;
line-height: 18px;
}
h1 {
font-size: 24px;
line-height: 36px;
margin-bottom: 18px;
font-weight: 200;
font-variant: small-caps;
}
h2 {
margin-bottom: 18px;
line-height: 18px;
font-size: 18px;
}
h3 {
font-size: 15px;
line-height: 18px;
}
h4, h5, h6 {
font-size: 12px;
line-height: 18px;
}
ul, ol {
margin: 0px 0px 18px 18px;
}
ul {
list-style-type: circle;
}
ol {
list-style: decimal;
}
td {
padding: 5px;
}
:link, :visited {
font-weight: bold;
text-decoration: none;
color: #036;
}
.blue {
color: #0000ff;
}
.red {
color: #ff0000;
}
With our new CSS we will notice at least a subtle difference in our RTE. In the following screenshot, we can see the original RTE on the left and the updated RTE on the right. As you can see, our text is now spaced out better and lightened to match the frontend:
As we have overridden the default classes without creating any new ones, the Block style and Text style drop-downs are both empty now. In the RTE, block styles are used for the “blocks” of our content such as paragraphs and headings while the text styles are applied directly to words or pieces of text within a larger block. Put simply, if we wanted a whole paragraph to be blue, we would use the Block style drop-down, and we would use the Text style drop-down if we only wanted a single word to be blue. Both of these drop-downs use our CSS classes for styling, so we’ll go ahead and create our new classes in the TSconfig.
Classes properties
All of the classes in our external CSS file (rte.css) are made available as soon as we declared the file with the contentCSS property. If we want to use them, we just need to associate them with a style type (paragraph, character, image, and so on) for the default RTE. If we wanted to associate the blue and red classes with text styles, for example, we would add the following to our page’s TSconfig:
RTE.default.classesCharacter = blue, red
Before we assign the classes to a type, we should declare them in the TSconfig so they show up properly in the RTE. By declaring the classes, we can set the titles we want to show in the RTE and how we want the titles to be styled in the drop-downs. Without declarations, the styles will still show up, but the titles will just be CSS class names. We want to declare them in TSconfig with specific title to make our editors’ lives easier. We can add the following code to the TSconfig to declare the classes in our RTE and set more descriptive titles that will be shown in blue or red in the drop-down menus:
RTE.classes {
blue {
name = Blue Text
value = color: blue;
}
red {
name = Red Text
value = color: red;
}
}
We can use CSS classes for more than just the text style, of course. The table below shows all of the main ways that we can associate and use classes in the htmlArea RTE, but you can read more in the htmlArea TSref. Go ahead and try some of them out with the example TypoScript lines that are shown.
RTE class properties
Toolbar properties
Along with what shows up inside the content of the RTE, we can modify the toolbar itself to control what editors are able to see and use. By controlling the toolbar, we can make the RTE easier for editors and make sure that the branding and styling is consistent. The table below shows some of the most useful properties we can use to alter the toolbar available to editors. We can actually go much further in editing the individual buttons of the toolbar, but this is changing enough between major releases that I recommend using the TSref as a reference for your version of the htmlArea RTE.
HTML editor properties
Finally, we can change the way that the RTE works with HTML. For example, the RTE uses paragraph tags (<p></p>) for all blocks in our text area, but we can replace this behavior with break tags (<br />) if we want. The RTE also strips certain tags, and we can change that with RTE properties as well. The following table shows the most common properties that we can use in the Page TSconfig to modify the HTML in the htmlArea RTE. Even if we don’t need anything else in this section; using allowTags to allow embedded video can make our editor“ lives easier if we want to embed YouTube or Vimeo players in our website. All of this information is also available in the TSref for the htmlArea if you need an updated reference.
