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).

Converting from TYPO3v4 to Phoenix

I'm working on converting a site I've built in TYPO3v4 to TYPO3 Phoenix (or Foo, or whatever the final name becomes). I'm going to document the progress and the pitfalls I run into on this blog.

Edit: Added link to related post (see end of this post).

Is it wise to use Phoenix in such a pre-alpha state?

For many, it is not a good idea to use such pre-alpha software, especially not for a site that is supposed to be a production site once conversion from v4 is complete.

That being said, you must understand something about me. Using Phoenix, or just reading the code that runs Phoenix, feels like a five year old opening presents on his birthday. Every review in gerrit and every commit in git is like a new present--they're all beautiful features that just make the geek inside me want to jump for joy.

Really, go read the code in FLOW3 and Phoenix. I've learned a lot about good software design by perusing the excellent examples of DDD, TDD, AOP, and any other programming buzzword you want to throw in the mix. Right now, FLOW3 and Phoenix are like a submarine where you can't see very much on the surface of the water (the UI), but when you go into the depths of the water, into the core of that submarine, there's just power--raw nuclear energy just begging to fly yours and my next project just as fluid and sleek as a submarine gliding through the water.

Phoenix also has a wonderful UI with a ton of potential. When you look at Phoenix's UI, you're looking at an Airforce Squadron that is ready to put on a show. When Phoenix launches, all you'll see is the bombs bursting in an awesome show of carefully crafted fireworks that will amaze even the most stubborn of executives. Aloha is simply a breeze. It's the lift that carries these airplanes and makes Phoenix soar above the rest of the CMS landscape. I look forward to not training editors and anyone else that wants to work with content. Aloha makes the editing process so simple, that I believe Phoenix could easily be the next wiki platform. Aloha is easier to learn than wiki language, and with the amazing security that courses through the veins of FLOW3 and Phoenix, I'll be able to open up the website to allow people to edit their own content without relying on a dedicated technical writer like me.

But what about all the rough edges?

Are there rough edges? Yes. Am I going to use Phoenix anyway? Yes. Will there be issues? Absolutely.

This is a challenge for me. Using Phoenix is something I've been toying with for years. The smooth features, for me, outweigh any of the rough edges I'll face.

I need forms, and TYPO3.Form is an awesome, simple way to build them.

I want to edit certain tables and bits of documentation as quickly as possible. Aloha is the key to that. I've already used some Aloha integration in v4, which has saved me hours of time that I would have spent manually editing the CSV tables in v4. Aloha is just an easier interface for all parties involved.

When I find a rough edge, I'll write about it. I'll post what I've discovered and what I'm doing to hopefully help others. I'll be the test case to help start discussions that need to happen to make Phoenix ready for a wider launch.

Just what does this transition from v4 to Phoenix entail?

For the site I'm building, I will deal with a variety of parts. Some parts don't even exist in my v4 site yet. Other parts do. In any case, much of the conceptual site design was completed in v4. These parts include (in no particular order):

  • Templating
  • Security (I need to have both pages, and individual elements that are only visible to certain usergroups).
  • Automatic deployment with JIRA and TYPO3.Surf
  • Custom plugin(s) to generate some of the content on the site
  • Generate forms (with TYPO3.Form) on most of the pages with generated content
  • Custom ViewHelper and plugin to generate a special menu to 'cascade' or merge pages and content across branches of a page tree based on who is logged in
  • Transition any content that could not be automatically generated from v4 to Phoenix.
  • Custom FLOW3 Package to export the content in a useable format to be consumed by external processes.

When I blog about these things, I'll focus on the parts that will spur discussions about Phoenix--like things that need to be developed further in FLOW3 or Phoenix--or that are more generally interesting. In much of this, I won't be able to share too much of the code I write, because it involves interacting with some of our proprietary APIs, but for much of what I'm working on, I should be able to share what I learn in the process.

Disclaimer: These opinions are my own, and do not necessarily reflect the opinions of my employer, InfoTrax Systems. InfoTrax is an international corporation that provides software solutions and consulting services to the MLM and direct marketing industry. My job is to document the developer oriented parts of our software such as the API we provide to our customers.