Introducing Hierarchical Menu in TYPO3

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.

Page tree concepts

We are about to dive into all of the little details, but there are a few basic concepts that we need to review first. So, we're going to make sure we have a more complete definition that avoids any confusion:

• Page tree: Our TYPO3 page tree is all of the pages and folders that we work with. This includes the home page, about us, subpages, and even non-public items such as the storage folder in our example site. If we have a very simple website it could look like this:
  • Home
  • About Us
  • Staff

• Level: Our page tree will almost always have pages, subpages, and pages under those. In TYPO3, these are considered levels, and they increase as you go deeper into the page tree. For example, in our extremely simple website from the example above both Home and About Us are at the base (or root) of our page tree, so they are on level 0. The staff page is underneath the About Us page in the hierarchy, so it is on level 1. If we added a page for a photo gallery of our last staff lunch as a subpage to the staff page, then it would be at level 2:
  • Home (Level 0)
  • About Us (Level 0)
  • Staff (Level 1)
  • Staff Lunch Gallery (Level 2)

• Rootline: TYPO3 documentation actually has a few different uses for the term "rootline", but for the menu objects it is the list of pages from your current page or level moving up to the root page. In our example above, the current rootline from the Staff Lunch Gallery is Staff Lunch Gallery | Staff| About Us

Before we look at all the different kinds of menus in TYPO3 and all their little differences, we need to explore the base TypoScript object for all of them: HMENU. HMENU generates hierarchical menus, and everything related to menus in TYPO3 is controlled by it. As the base object, HMENU is the one thing that every type of menu is guaranteed to have in common. If we understand how HMENU is creating its hierarchical menu, then everything else is just styling.

We can already see an example of HMENU being used in our own TypoScript template setup by looking at the menus that the TemplaVoila Wizard generated for us:

## Main Menu [Begin]
lib.mainMenu = HMENU
lib.mainMenu.entryLevel = 0
lib.mainMenu.wrap = <ul id="menu-area">|</ul>
lib.mainMenu.1 = TMENU
lib.mainMenu.1.NO {
allWrap = <li class="menu-item">|</li>
}
## Main Menu [End]

## Submenu [Begin]
lib.subMenu = HMENU
lib.subMenu.entryLevel = 1
lib.subMenu.wrap = <ul id="submenu-area">|</ul>
lib.subMenu.1 = TMENU
lib.subMenu.1.NO {
allWrap = <li class="submenu-item">|</li>
}
## Submenu [End]

We can see that the wizard created two new HMENU objects, lib.mainMenu and lib.subMenu, and assigned properties for the entry level and HTML tags associated with each menu. We're about to learn what those specific properties mean, but we can already use the code from the wizard as an example of how HMENU is created and how properties are defined for it.

Types of menu objects

The HMENU class does not output anything directly. To generate our menus, we must define a menu object and assign properties to it. In our current menus, the TemplaVoila Wizard generated a menu object for each HMENU in the following highlighted lines:

## Main Menu [Begin]
lib.mainMenu = HMENU
lib.mainMenu.entryLevel = 0
lib.mainMenu.wrap = <ul id="menu-area">|</ul>
lib.mainMenu.1 = TMENU
lib.mainMenu.1.NO {
allWrap = <li class="menu-item">|</li>
}
## Main Menu [End]

## Submenu [Begin]
lib.subMenu = HMENU
lib.subMenu.entryLevel = 1
lib.subMenu.wrap = <ul id="submenu-area">|</ul>
lib.subMenu.1 = TMENU
lib.subMenu.1.NO {
allWrap = <li class="submenu-item">|</li>
}
## Submenu [End]

There are a handful of classes for menu objects that can be used by HMENU to generate menus in TYPO3, but we are going to be concentrating on the two most powerful and flexible options: TMENU and GMENU.

The TemplaVoila Wizard used TMENU in our current menu, and it is used to generate text-based menus. Menus built with TMENU output the title of each page in the menu as a text link, and then we can use HTML and CSS to add styling and layout options.

Menus created with the GMENU class are considered graphic menus. We can use GMENU to dynamically generate images from our page titles so that we can use fancy fonts and effects like drop-shadow and emboss that are not supported in CSS by all browsers equally.

Menu item states

The menu system in TYPO3 allows us to define states for different menu options. For example, using the state definitions, we can customize the behavior of menu items when they are active or rolled over. The normal state (NO) is available and set by default, but all of the menu item states must be enabled in TYPO3 by adding code to our template like this: lib.mainMenu.1.ACT = 1. All menu objects share a common set of menu item states from the table below:

HMENU properties

Because HMENU is the root of all of our other menu objects, any of the properties that we learn for HMENU will be applicable to all of our menu options that we might use on future websites. I've included a list of the TypoScript properties that we are most likely to use in the TypoScript template setup, but you can see the complete list in the TSref (http://typo3.org/documentation/document-library/references/doc_core_tsref/current).

If you haven't used TypoScript much, and this is too much information all at once, don't worry. It will make more sense in a few pages when we start experimenting on our own site. Then, this will serve as a great reference.

As we've already witnessed in the main menu, TYPO3 sorts our menu by the order in the page tree by default. We can use this property to list fields for TYPO3 to use in the database query. For example, if we wanted to list the main menu items in reverse alphabetical order, we could call the alternativeSortingField in our template:
lib.mainMenu.1 = TMENU
lib.mainMenu.1.alternativeSortingField = title desc