The “optionsplit” within TypoScript is a very powerful feature to manipulate the output of repeating elements. This is especially helpful, if you do not know how many elements will be there. In this post I will show you, how that works.

Last week an apprentice came to me with a task, he had to solve, but was still looking for a solution. The first thing, that came to my mind was: That is something to solve with an “optionsplit”. At the same time I was quite uneasy how to explain that in understandable words (I remember the time of my first integrator exam and that topic :-| ).

At the end of the introduction, he said: “That’s not that complicated. Whats the issue?” These words motivated me to write this article.

Purpose of “optionsplit”

The optionsplit can be applied to any TypoScript object, which has more than one element and each of them must get another value.

A quite usual example is a menu, where the various element get different values applied, As an example, I will use a menu where I apply different “ATagParams”.

Complete “Optionsplit” – Example

Here are five steps how to understand and master the “optionsplit” in your project:

Step 1: Menu with 3 elements

A simple menu would have this typoscript code:

lib.myMenu = HMENU
lib.myMenu {
   1 = TMENU
   1 { 
      ATagParams = class="standard-class"
   }
}

This code will add the class attribute to every A-tag in this level of the menu. But usually there are cases where you would like to have different params applied to the link tag, depending on there position in the menu: The last one should be formatted in another way, than the first one.

This is where the optionsplit comes in. The optionsplit splits the provided options into several parts. The separator is the string |*|for the main parts. In most cases there will be three of them, which is also the maximum number of “optionsplit”s.

The example from above now could look like:

lib.myMenu = HMENU
lib.myMenu {
   1 = TMENU
   1 { 
      ATagParams = class="first-class" |*| class="standard-class" |*| class="last-class"
   }
}

This would lead to an menu, where the first menu link has the CSS class “first-class” set, the middle one “standard-class” and the last one “last-class”.

This matches probably your expectations. But let’s go to step two, where there are more than three menu elements

Step 2: Menu with 5 elements

The output will look like this, if there are four elements

<a class="first-class" href="link1">My first Page</a>
<a class="standard-class" href="link2">My second Page</a>
<a class="standard-class" href="link3">My third Page</a>
<a class="standard-class" href="link4">My fourth Page</a>
<a class="last-class" href="link5">My last Page</a>

But why that? Because the optionsplit is not applied from left to right, as it seemed in step one. The procedure starts with the last part class="last-class", then the first part is applied class="first-class". If it is finished the middle part is applied to the rest of the remaining elements.

Just to apply the main parts with the separator |*| pobably will not be sufficient in all cases. Therefore another seperator exists, which introduces subparts.

Step 3: Introduce subparts

Each of the main parts splitted by |*| can be divided into subparts. The divider for subparts is ||. Subparts can be applied to every main part. There is no limitation in the count of subparts. The extended example from above looks like this

lib.myMenu = HMENU
lib.myMenu {
   1 = TMENU
   1 { 
      ATagParams = class="first-class" || class="next2first" |*| class="first-standard-class" || class="second-standard-class"|| class="third-standard-class" |*| class="next2last" || class="last-class"
   }
}

The same rules as in step two apply:

1) Apply the third main part. Within the third main part, start with the last subpart and apply them from the “right” end.

2) Apply the first main part. Within the first main part, start with the first subpart and apply them from the “left” end.

3) Apply the main part to the remaining elements. If there are more elements then subparts available, loop over them.

Consider that we have a menu with nine elements, the output will look like this:

<!-- first main part starts // applied second starting with "link1"-->
<a class="first-class" href="link1">My first page</a>
<a class="next2first" href="link2">My next 2 first page</a>
<!-- center main part starts // applied third-->
<!-- first loop in center main part starts -->
<a class="first-standard-class" href="link3">My first standard page</a>
<a class="second-standard-class" href="link4">My second stadard page</a>
<a class="third-standard-class" href="link5">My third standard page</a>
<!-- second loop in center main part starts -->
<a class="first-standard-class" href="link6">My first standard page</a>
<a class="second-standard-class" href="link7">My second standard page</a>
<!-- center main part ends -->
<!-- last main part starts // applied first starting with "link9" -->
<a class="next2last" href="link8">My next 2 last page</a>
<a class="last-class" href="link9">My last page</a>

Step 4: Only two main parts

There might be the situation that only one |*| main separator is in the code. That means, that there is no “last main part”. The optionsplit starts with the appliance of the “first main part”, and then loops over the “center main part”.

Here is an example, based on step three:

lib.myMenu = HMENU
lib.myMenu {
   1 = TMENU
   1 { 
      ATagParams = class="first-class" || class="next2first" |*| class="first-standard-class" || class="second-standard-class"|| class="third-standard-class"
   }
}

In this TypoScript example the last main part from step 3 was just cut off. So the result will look like this:

<!-- first main part starts // applied second starting with "link1"-->
<a class="first-class" href="link1">My first page</a>
</a><a class="next2first" href="link2">My next 2 first page</a>
<!-- center main part starts // applied third-->
<!-- first loop in center main part starts -->
</a><a class="first-standard-class" href="link3">My first standard page</a>
</a><a class="second-standard-class" href="link4">My second stadard page</a>
</a><a class="third-standard-class" href="link5">My third standard page</a>
<!-- second loop in center main part starts -->
</a><a class="first-standard-class" href="link6">My first standard page</a>
</a><a class="second-standard-class" href="link7">My second standard page</a>
</a><a class="third-standard-class" href="link8">My third standard page</a>
<!-- third loop in center main part starts -->
</a><a class="first-standard-class" href="link9">My first standard page</a><a class="third-standard-class" href="link8">
<!-- center main part ends -->
<!-- last main part is empty -->
</a>

Step 5: Use in wraps

This step is nothing new. I want to point out that there is another level of difficulty in readability. The optionsplit can also be applied to a “wrap”. So there is still one more pipe | in the syntax available.

Here is a single line, how it may look like:

lib.myMenu = HMENU
lib.myMenu {
   1 = TMENU
   1 { 
      wrap = <li class="first-class">|</li> || <li class="next2first">|</li> || <li class="next3first">|</li> |*|<li class="first-standard-class">|/li> ||	<li class="second-standard-class">|</li> ||<li class="third-standard-class">|</li> |*| <li class="next2last">|</li> ||<li class="last-class">|</li>
   } 
}

Yeah, that’s quite a forest of pipes |. But you do not to get confused. If there is third party to understand, I have a best practice for you:

Best practice to understand an optionsplit

With these five steps you can understand and debug any optionsplit, which comes across your way:

1) copy the complete code of the option split to another text editor or file

2) make line breaks before and after each main part separator

3) indent the non separator lines

4) make line breaks before and after each subpart separator

5) indent the non separator lines

Due to the indents it’s easy to recognize and to apply the rules. Then it’s possible to understand what’s happening and to find possible bugs.

Full formal ruleset for TypoScript “optionsplit”

The examples above can be formalized in the following seven rules.

1) The items of the last mainpart are used first.

2) For last mainpart the start position of subparts is as close to the end as possible.

3) The items of the first mainpart are used second.

4) For first mainpart the start position od subparts is taken from the beginning.

5) The items of the center mainpart are used third.

6) For center mainpart subparts are taken from the beginning and the whole center sequence is repeated from the beginning as long as necessary.

7) If there is only one main part separator, only first and center mainpart are available, so the rules 1) and 2) do not apply.

Conclusion

Regarding my first TYPO3 Certified Integrator exam, I feared the optionsplit most. I hope that this explanation of the TypoScript function “optionsplit” helps you to understand what you can be achieve with it. There is no need to fear this feature.

If you profited from this post or you know somebody, who could profit from it, please share this post via your favorite social network. For your convenience I added some share buttons at the end of this page.

Credits

I want to thank my supporters via patreon.com, who made this blog post possible:

• Tobias Wollender (@chapi): He was my very first supporter via patreon.com
• Carsten Falkenberg (@limeboxIT)

If you appreciate my blog and want to support me, you can say “Thank You!”. Find out the possiblities here:

I found the blog post image on pixabay . It was published by Schak under the CC0 public domain license. It was modified by myself using pablo on buffer.