Screencast

If you don't feel like following the tutorila step by step, you may want to watch the screencast based on it.

Creative Commons License
Tesseract Tutorial: Getting Started by François Suter is licensed under a Creative Commons Attribution-NonCommercial-NoDerivs 3.0 Unported License.
Based on a work at www.typo3-tesseract.com.

Support the project

If you appreciate what the Tesseract project does for you, consider donating to it.

Scenario

Here's what we want to achieve in this tutorial: imagine a web site – possibly an intranet – where we want to have a list of BE users somewhere in the frontend, so that visitors can easily contact the web site administrators.

This tutorial will show that this can be achieved with a minimum of efforts and a minimum of redundant components. Further tutorials will improve on that list.

Preparing for work

Before starting the actual work, create a new page somewhere in your page tree so that we can start with a blank slate. Call it “Web site administrators”.

Place yourself on this new page, in Web > List mode.

Querying the database

As a first step we will use Data Query to get a list of all BE users. We want to display their names and email addresses so that the web site users can contact them easily. Create a new “Data Queries” record and type in the SQL query:

Writing the SQL query

Data Query takes care of all “special” fields automatically, so you don't need to care about them. In this case it will transparently handle the “disabled” field meaning that disabled BE users will not be listed, although we didn't specify this condition explicitly in the SQL query.

WARNING: be sure to type the query as it appears in the above screenshots, with the SQL keywords in uppercase. Data Query requires SQL keywords to be in uppercase.

Let's not worry about the other properties for now. Just save and close the Data Query record.

Preparing a template for display

The next step is to start preparing the display for the results of our query. To achieve this, create a new record of type Template-based Display. Just enter a title and save. You should have a screen that looks like this:

The empty templatedisplay record

The main action happens in the mapping “Fields”. At the moment there's nothing we can do in the “Mapping” tab, but we can switch to the “HTML” tab and start defining a template for displaying the list of BE users. Enter the following HTML:

A simple HTML template

The basic idea is to display the BE users as a bulleted list. So the first step is to open and close a <ul> tag. Inside that tag we define a loop on the “be_users” table, using the syntax which is explained in more details in the manual of the Template Display extension. Inside the loop, we create a <li> tag for each user and decided to display the name and the email side-by-side, the email being wrapped in brackets.

We can move back the the “Mapping” tab. The HTML that we just entered is saved in the background. You should now have the following view:

The mapping interface, without data

As you can see that HTML was parsed and some elements were recognized and highlighted: the loop and the “field markers”. Those markers are where the data from the database will come. They currently have warning icons over them because they are not yet related to a database field, even though the use the same name. In the current situation, the “Data Queries” record that we created in the previous step and the template are not related in any way.

In the next step we will define the actual content element and make the relation between the query and the template. For now you can save and close the “Template-based Display” record.

Fitting it all together

It is finally time to use the Display Controller itself. Move to the Web > Page module and create a new “Display Controller (cached)” by choosing from the new content element wizard:

Creating a Display Controller with the new content element wizard

See the “User's manual” chapter for a discussion on the difference between the cached and non-cached versions.

Switch to the “Data Objects” tab to create the relations between the components we defined earlier. For the “Data Consumer” select “Template-based Display” record that we just created. For the “Primary Data Provider” select the “Data Queries” record created in the first step. Click on the “Save” button. Your screen should look like this:

The Display Controller with all defined relations

Now the “Template-based Display” record has been set in relation with the “Data Queries” record via the Display Controller. It's time to edit the “Template-based Display” record and define the relations between the database fields and the template markers. Select the “Template-based Display” record and click on the pencil icon:

Editing the Data Consumer

In the new window, click on the ###FIELD.realName### marker. Notice the drop-down menu that has appeared on the right side. Also note that the “realName” field is preselected in this drop-down menu. That's because the marker used the exact same name as the database field.

Below the “fields” drop-down menu is another selector called “Types”. This defines how the field should be rendered. You will notice that some items in this selector bear names that resemble TypoScript content objects. This is no coincidence. For example a field of type “text” will be rendered using a TEXT object. The box below the selector allows you to enter TypoScript corresponding to the type that you selected. The Template Display manual has a list of all types and their corresponding TypoScript objects or functions.

Mapping the user's name

In this case we don't want to do anything special with the administrator's name, so we don't need any TypoScript rendering. Hence we choose the “Raw text (no transformation)” type and click the “Save field configuration” button below the TypoScript configuration field.

Configuring the user's name mapping

Notice how the little icon next to the pencil changed after clicking on “Save field configuration”. This is a quick visual clue as to the type of the field.

Let's move on to the next field where we will use some TypoScript. Indeed we want the e-mail address to be clickable. So the steps to take are:

  1. click on the ###FIELD.email### marker
  2. verify that the “email” field is indeed selected in the “Fields” selector
  3. choose the type “Email” from the “Types” selector
  4. click on “Save field configuration”

Your display should look like this:

Mapping the e-mail field

The “Email”-type field corresponds to a “typolink” function. It expects that the field it is mapped to contains an e-mail address, otherwise it will just create a typolink to whatever else.

We are ready for the big jump! Save and close the edit window and then view the page we have been working on. You should see a list of BE users with a clickable e-mail address (the screenshot is based on the Introduction Package):

A first result in the FE

What's wrong with the first line? That's quite simple: this BE user has no real name and no e-mail address defined. This gives us a good opportunity to improve our example.

Improving the display

A first approach could to just filter out users that have no real name or e-mail address in the SQL query itself. This is a bit rough. We can do better with some more TypoScript in the display.

First of all let's edit the SQL query so that we have the username at disposal too. Edit the “Data Queries” record and add the “username” field to the list of selected fields:

Adding the username to the query

Now let's edit the “Template-based Display” record again. We want to achieve the following: if the real name is not defined, we want to display the username instead. This will be possible only with TypoScript so we have to change the type of the “realName” field to “text” and then enter the following TypoScript:

ifEmpty.field = username

Adding some TypoScript to the user's name configuration

NOTE: don't forget to click the “Save field configuration” button every time you make a change either to the “Fields” selector, the “Types” selector or the “TypoScript configuration” field.

Let's look at the result in the frontend:

The improved view in the FE

The username has indeed replaced the missing real name for the first user.

How was that possible? For each record handled inside the loop, Template Display loads all fields from the record into the local content object used for rendering. Thus every field is available in the “field” property of stdWrap. This makes it very easy to use the data from the database to create sophisticated renderings. It this case we are using this together with the “ifEmpty” property, so that the username gets displayed when the real name is blank.

The second improvement would be to avoid displaying empty brackets when no e-mail address is defined. This is left as an exercise to the reader. The answer can be found below (don't look ahead). Just a hint:

  • the “Email”-type field corresponds to a typolink function. This implies that we will not have the TypoScript available to avoid displaying empty brackets. The type of the field will have to be changed and the “mailto:” link built differently. And the HTML template has to be changed too, of course.

The result should be as follows:

Hiding the brackets entirely when no e-mail is defined