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.

Menuing

I used the fed:page.menu 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 fed:page.menu allows me to include the menu inline between the fed:page.menu 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:

• Converting from TYPO3v4 to Phoenix (provides context for this project)

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.

Related Posts:

• Fluid Templating--from v4 to Phoenix

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.

Expanding the TYPO3 Form Builder Concept

I think the new Form/FormBuilder packages are an amazing addition to FLOW3. Here are some ideas to expand on that solid foundation.

Point Number One: UI Theme-ing

Phoenix needs a cool UI? No. Let's try again:
Phoenix needs a cool Theme-er (api and theme builder)

Arguably, WordPress and Drupal are as popular as they are because of customize-able eye candy. From what I've read (I don't remember where), WP had an ugly default theme for a long time. They built a solid core and the design community took off making custom themes, because, of course people didn't want to stick with the default ugly theme. Drupal is also popular with themers. The way Drupal is designed, people had to theme much of the backend whenever they created a new template/theme for the frontend (though the distinction between front and back ends is much fuzzier in Drupal than in TYPO3). Themes gave people, and the organizations they served, a sense of pride and ownership. "I did that!"

Perhaps you've used Trillian, the instant messenger? Several years ago, I was getting into theme-ing that beast because I wanted it to look different. An entire community of themers has grown up around Trillian, and a variety of other products. People love to style things their own way.

I say, make it theme-able and they will come. I like that the user interface doesn't feel totally polished right now. I think that leads us down the same path that WP took. I think we should use everything Jens did to create a themeable foundation. We organize the system with links across the top, typically stylized as tabs. We have a page tree and various other UI concepts that can live in phoenix no matter what they look like. I would like to see something to help people generate themes for Phoenix; something that will make theme-ing fun and very approacheable; something that says "Phoenix helps you be yourself".

It's interesting to note that the themeing capabilities of  TYPO3v4 never really took off. I'm guessing the system was too complex, and all of the extensions (TV comes to mind) took forever to support changes in just the default theme, let alone support any other themes. So, I think there needs to be some kind of theme-ing api. I'd imagine that extensions/plugins would register any new elements or icons through this api, and access the current theme's ui elements through the same. If a theme doesn't have something, then it falls back to the default or something like that.

So I guess that's two components: a graphical Theme Builder and a sweet Theme API that all phoenix extensions/plugins use.

Point Number Two: Phoenix Visual Framework and App UI Builder

Phoenix will have a lot of pretty standard UI elements.


Perhaps we can call these elements a visual framework and make them easy to use.

• The page tree will be available in a lot of places.
• The various Form elements will be ubiquitous (dropdowns, textareas, radio buttons, etc).
• Handling system feedback like errors or "processing..." or whatever will be all over the place.
• The various menus across the top or the context sensitive menus (like aloha's floating toolbar, or a right click menu)

When someone builds a new module/extension, in many cases they will need to create an interface to interact with it. The Form API and Form Builder look perfect for this, except that not everything is a form. Navigational things like the page tree or the menu of tabs across the top are not really form elements and I doubt we'd want to make the entire backend dependent on the Form API. I'm open to other thoughts on this, maybe we do want to build everything in the backend with the Form Builder, I don't know. I do, however, think that we need something; Something very much like the form builder that can create the fluid templates for use in Phoenix; Something that will help extension creators to use the theme api from the get-go; Something that will help to create a standard way to create user interface in Phoenix.


In this UI Builder, devs should be able to quickly say, include the page tree, and a menu across the top, and a content-editable element in the main section to use Aloha during data input, and a Form, probably designed in the Form builder, to show up in this section over here. The UI Builder builds on the theme-ing api to encourage developers to use the standard Phoenix elements before creating their own. Of course, devs can always drop down and add stuff in fluid and handlebars, but if they 80/20 rule is true, then 80% of the time, the standard elements will do, so they shouldn't have to rebuild them all the time.

I'd imagine that such an App UI Builder would be used to quickly put together functional mock-ups of the desired functionality before completing the data model and whatever controllers are needed.
So, Phoenix needs a visual framework of standard elements, a UI Builder that makes it easy to use those elements.

Point Number Three: Fluid Template Builder

I think the Builder concept could also be applied to creating templates.

Drupal and WP afficionados love creating themes and sharing them. There have been several different efforts to create the same share-ability with  TYPO3 v4's various templating systems, but none have attracted the attention needed to create a truely competitive library of templates that people can try and use as the basis for their own template. The social buzz generated by the "I made that" thought is really important to capture with this new version of  TYPO3 - our friend the Phoenix. I think that we could one-up the competition by extending the Form Builder concept, and the Application UI Builder concept mentioned above, and create a Fluid Template Builder to get people up and running as fast as possible.

There are standard template elements like menus, videos, columns, etc. Each of these elements can be created in Fluid/TypoScript (a la the Form API/Builder) and then people can create basic Fluid templates with drag and drop. They say "I want a three column layout" and then they drag a menu into the left column and say that the middle column is editable content. It would only support a limited number of things, but it would let people get into the flow with fluid, even faster.

On the other hand, this could also be something like the TV wizard where a designer or design team has created an html template that you must now 'fluidify'. They select the elements that need to be replaced, and either drag the standard fluid elements into replace them or they edit the fluid template in a kind of text box at the bottom of the page (think ide). It would also be nice to select, say, a menu that the designer created with ul and li tags. then a kind of modal wizard that runs through and helps to generate the fluid loops required to create the menu.

Point Number Four: Third Party Visual Frameworks

The catalysts for all of these thoughts are: The sweet new TYPO3.FormBuilder and the LDS Church's IxF (Interaction Framework).

I take a special interest in this organization because I'm a member of the Church of Jesus Christ of Latter-day Saints (members are also known as Mormons). The Church has a huge technology department of at least a couple thousand people. There are so many disparate development efforts (lots of web apps created mostly for internal use by other employees) that Aaron Barker (a UX designer who works for the Church) built an awesome Interaction Framework (IxF). I hope that final approvals will happen sometime soon so that the IxF can be used in things other than Church projects. For now, sadly, it's not publicly available, so I can't show it off to too many people.

In the meantime, as Phoenix matures, I would love to see some of the Church's PHP projects use  FLOW3 on the backend, with IxF as the standard frontend. I think one way to encourage that would be to create the App UI Builder, as described above, that uses the IxF elements. That way devs can generate the already standardized UI even faster in a visual interface like (based on) the Form Builder. This way,  FLOW3 becomes an easy choice - build the forms with this nice visual tool, and naturally they'll end up using the amazing  FLOW3 framework.

In the Form Builder, you have something like:
Form > Page* [> Section]* > Element*

That's somewhat analogous to the organization of IxF:
Template > Layout* [> Section]* > Element*

There are 4 basic templates (the IxF calls these Layouts as well, but they're more like super-layouts because they consist of the whole page, the stuff that goes around the internal layout).
6 standard layouts (inner layouts that go inside an outer layout/template) accessible from the Layouts section of the IxF docs.
Several section elements that allow for organizing other elements (like tabs or accordians).
And other standard widgets/elements are in the "Demos & Examples" section of the IxF docs.
Templates (accessible from the Interaction Framework menu in the upper left):

• The main IxF template demonstrated by the IxF docs (with the outer border that you can change colors).
• IxF Sign In Page
• IxF Alternate Layout - Fixed Small App (for simpler, or mobile apps)
• IxF LDS.org (this one is important as most public facing apps have to use this template.)

Currently the extent of publicly available info about IxF resides on Twitter: @ldsixf

Tying it all together

In the main IxF template, some of the elements in the top bar that are very similar to some of the Phoenix concepts. - messaging in the upper right, and app sections in tabs across the top.

I would love to be able to have a theme that reused the IxF elements in Phoenix itself (Point Number 1 above). When it comes time to try and convince people to switch over to Phoenix, that would be a very sweet spot to say "and see, it even uses the IxF". The App Builder (Point Number Four, based on Point Number Two) would help with  FLOW3 adoption now, before Phoenix is ready. Point 3 is, well, just because I think that would be way cool for Phoenix to have that to try and expand  TYPO3's potential market.

I'd imagine that other organizations would like to have their own theme used in Phoenix and other  FLOW3 based apps as well. I hope that this stuff can be generalized/abstracted enough to make it useful to more than just the Church. Maybe the themer would allow me to change the classes that are applied to different kinds of elements so that I can use standard stylesheets from whatever project I choose (not just twitter bootstrap, but the IxF or whatever else).

The only hangup (admittedly a significant one) with using the IxF, is that we have to wait for IxF to be open sourced - which should happen afaik, I just don't know when. I really hope sooner than later.