Wednesday, July 11, 2012

Fluid Templating--from v4 to Phoenix

This post explores my experience transitioning from v4 templates to Phoenix+Fluid Templates.

Templating in TYPO3v4

There are a lot of ways to build a site in v4, including "Modern Template Building" (autoparse templates), TemplaVoila, and now we can use FLUIDTEMPLATEs. The site I am converting originally used the templavoila_framework, but a couple of weeks ago, I made it use a FLUIDTEMPLATE instead.

Each of these methods--the templavoila_framework and FLUIDTEMPLATE--gave me some basic templates to get the site I'm working on up and running fast. One of the keys in choosing the templavoila_framework and then fluid was aesthetics and useability. The site had to look great without using a designer to get it off the ground. Useability is more important than appearance, but aesthetics play a role in useability (If it's ugly, most people don't want to use it). Plus, the site has to look 'polished' for those moments when the sales team is using the docs site as a sales tool to help potential clients understand that their developers will be able to interact with our API.

From templavoila_framework to FLUIDTEMPLATE

One of the issues I faced with the templavoila_framework (and templavoila in general) was the effort involved in migrating a template to Phoenix. It would take significantly more effort to convert from the TypoScript and TemplaVoila based approach to fluid, than it would take to go from a FLUIDTEMPLATE in v4 to a fluid template in Phoenix.

At T3CON12CA, Bastian Waidelich shared how he sets up his FLUIDTEMPLATEs in TYPO3v4. His example site package is available on Github. Bastian's template uses Twitter Bootstrap, which turned out to be a perfect match for the documentation site I'm working on. It's elegant and can handle multi-column content just fine. Bootstrap also gives me great styling for forms, which I'll be using later on as I develop the site. So, I converted the v4 site from the templavoila_framework to use a Site Package based on Bastian's example site package using Twitter Bootstrap.

The result? Fast beauty. It only took me a week to finish the Bootstrap based template and get it integrated into TYPO3v4. One of those days was spent generating an appropriate logo for the site. Overall, for my first time using FLUIDTEMPLATEs, I was very pleased with how little time it took to get up and running.

Templating in TYPO3 Phoenix

I'm currently in the process of converting that FLUIDTEMPLATE into something that Phoenix can use. I just copied most of the Resources folder from my v4 extension to my FLOW3+Phoenix Site Package.

Then, I had to modify the template to work with the ViewHelpers that are available in Phoenix.

Then, I had to modify the template headers, because Phoenix controls the output more than my v4 setup did (I had disabled all head output in v4). As part of modifying the headers, I discovered that the FLOW3 version of Fluid is a lot smarter about linking to the right files for stylesheets. Instead of using an f:uri.* ViewHelper, I could just include the relative location of the stylesheet, and Phoenix automatically cleaned it up to use the base url to the correct resource (props to the devs. :D This feature is awesome).

I also dropped using the f:uri ViewHelper to include the JavaScript files at the end of body.

After some more refactoring, most of the template is working well--Phoenix is inserting content elements right where I told it to.


I used the ViewHelper in v4, so I had to replace that with my own fluid templates for menuing in Phoenix. Though TYPO3.TYPO3 provides some nice fluid templates with a great ViewHelper for menuing, they didn't allow me to include the bootstrap classes in the various elements. So, I copied the menu templates into my Site Package, and modified them to include the bootstrap markup+classes, as well as re-using some menu partials that I'd already written for use in v4.

I would like to see something that's a little more flexible for generating menus. For example, I really like how allows me to include the menu inline between the tags. The ViewHelper just adds the {items} variable in the fluid template to assist in generating the menu.

Terminology: Layout, Template, Partial

On another note, I've seen the word "template" used in a variety of contexts. However, I don't see anywhere in the docs that explain the difference between layouts, templates, and partials. I would appreciate some feedback to make sure I'm using these terms and resource paths correctly.

From what I understand, there's a kind of hiearchy of these template components. The Layout includes Templates. Templates can include other templates or partials. Partials might include other partials.

A layout (stored in Resources/Private/Layouts) Is the overall outline of a fluid template. It seems that TYPO3.TYPO3 already provides its own layout, so Site Packages don't really need to have a Layouts folder, right? But then, what if you have more than one layout for your site, but you want to have separate templates.

A template (stored in Resources/Private/Templates) controls the the presentation of a section (or more) of a particular layout. TYO3.TYPO3 defines one main section that encloses everything in the body tags--it's appropriately called the "body" section. Phoenix also defines a section for additional headerData and stylesheets. Beyond that, you have to somehow control where everything goes in the body section. If you want to include JavaScript at the end of the body tag, then include that in the template. I'm not sure how to handle the case where the site has more than one template for your site.

Partials (stored in Resources/Private/Partials or Resources/Private/Templates/Partials) are short sections of code that can be used and reused anywhere in your template. For example, I use a set of recursive partials for an unlimited depth menu.

Using Multiple Templates

When you want to use multiple templates in v4, the Backend Layout field is used to feed the {layout} variable in the template. However, there's no UI in Phoenix [yet] for selecting templates.

I guess as a stop-gap, I can create a TypoScript object that inserts a similar layout variable... Or perhaps there's a way to inject a variable in the fluid template based on where in the page tree it's being rendered? Does Sites.xml provide a way to have custom variables that are made available in Fluid?

I'll start grepping+reading more of the phoenix code tomorrow to see if I can find such a thing, but if someone else has already worked this out, that'd be awesome. Please let me know in the comments.

Related Posts:

Disclaimer: Opinions here are my own, not my employers (InfoTrax Systems).