21/07 2013
Flux Forms Revisited

We have got some extraordinary news for you. It's quite delicious so please take your time and get down to paper (here).

Reading this as a whole is recommended even if it is a bit long. You could jump directly to and read only "Breaking Changes" but this way you'd risk missing too much.

New Stuff

Flux as an extension generating FlexForms itself being a good idea; it was time to clean up the backyard. We didn't reinvent the wheel, rather implemented an OOP-approach to creating those forms. You know such concepts from for example the Symfony form component where you could actually pretty easily do things like:

/** @var Tx_Flux_Form $form */
$form = $this->objectManager->get('Tx_Flux_Form');
$field = $form->createField('Input', 'myfield', 'My input field');
$field->setDefault('My default value')
$structure = $form->build();


Notice the nice shorthand syntax? That is sugar we badly needed to properly maintain the ViewHelper collection in flux. You can imagine this involved quite a few changes but in the end simplified the structure of the neccessary ViewHelper code. Now, each VIewHelper corresponds directly to a matching Form Component - which means you can now even build your forms in PHP. Of course this type of usage will be covered in more detail later, in an article dedicated to this subject.

But unfortunately this also means that the ViewHelper API had to be changed in some aspects - but don't fear: they are easily migrated.

Since this is a major change which also opens up a new API for you to use, we decided that the next TER version and tagged release of Flux will be called 7.0.0. These changes are already committed on Github. We hope you will enjoy it!

Breaking changes

Event though the breaking changes can be looked up in the Pull Request on GitHub (<link https: github.com fluidtypo3 flux pull>github.com/FluidTYPO3/flux/pull/226) here is a list:

Removed ViewHelpers and arguments

  • flux:flexform.field.group has been removed
    • Migration: replace with specific implementation, "select", "inline", "tree" or "relation"
    • Planned: addition of flux:flexform.field.multiRelation to support the edge-case of a field having 1:n relations to multiple tables (in TCA speak, a "group" field with internalType "db" and multiple tables in the "allowed" parameter)
  • flux:flexform.field.html has been removed
    • This ViewHelper was purely an alias of flux:flexform.field.custom which still exists.
    • Migration: 100% interchangeable with the "custom" field type
  • flux:flexform.field.hide has been removed
    • Reason: field output suppression is an integrator task.
    • Migration: there is none
    • Tip/alternative: integrators and/or extension developers should modify TS for css_styled_content to get the same effect (static TS also usable)
  • All included FlexForm "Objects" located under flux:flexform.object.* have been removed.
    • Migration: there is none; if you were one of the few people who used any of these objects, you can find both the ViewHelper and template source online and restore these by adding them to your own extension. You are welcome to contact us for assistance in this matter!
  • flux:flexform.grid.row and flux:flexform.grid.column ViewHelpers:
    • repeat and iteration argument droppped.
    • Usage of ordinary control structures is advised, such as v:iterator.loop or f:for

Renamed arguments

  • flux:flexform.inline argument foreignTable renamed to "table" to match other relation ViewHelpers
    • Migration: rename argument when encountered in templates
  • All wizard's title attributes renamed to label for consistency
    • Migration: rename argument when encountered in templates

Special: The "select" ViewHelper

This particular ViewHelper is one of the most significant changes and possibly the one with most impact. The ViewHelper has been split into two: the current "select" field ViewHelper which now only works with preconfigured items (no relations) and the new "relation" field ViewHelper which supports all the relation-type fields (apart from the "inline" type which has its own ViewHelper).

  • flux:flexform.field.relation has been added
    • This new ViewHelper contains all relational type fields based on <select> or derivatives
  • flux:flexform.field.select ViewHelper:
    • DB relations are no longer supported by this ViewHelper.
    • Migration: swtich to flux:flexform.field.relation, flux:flexform.field.inline or flux:flexform.field.tree - whichever type you prefer
    • items attribute is now mandatory but also supports CSV values
    • commaSeparatedItems removed - the same value type can now be used in the "items" attribute
    • All DB relational attribute controls removed - to be replaced by flux:flexform.field.relation or subclass hereof (fx "inline")
    • Migration: replace usages with specific implementations

We realise this list is indeed rather long and does contain many changes - but do not fear. Migration is much less problematic than it first appears. Most of the changes can be done using search/replace - and with our recommendation for error dection it's even easier. Since every last breaking change is located inside the ViewHelpers for Flux, you will most likely never have to look beyond the top section in each Flux-based template to find all problems caused by these changes.

We of course apologise for the extra work this will cost you - but hope that you can save it, and more, because of the new Form Component feature and its integration into the ConfigurationProvider.

Scanning for breaking changes in your templates

The best recommendation possible at this time is to use EXT:builder - <link https: github.com fluidtypo3 builder>github.com/FluidTYPO3/builder or <link http: typo3.org extensions repository view builder>typo3.org/extensions/repository/view/builder - or just extension key "builder" in the extension manager. This extension contains a quick method to scan all your templates files (in a specific extension so you can do them one at a time if you have multiple extensions). By installing builder and executing this CLI command:

./typo3/cli_dispatch.phpsh extbase builder:fluidsyntax --extension <extensionkey>


You will receive a list of errors reported by each template - for example "unregistered argument 'foobar'" or "missing required argument 'foobar'" - which can then be fixed. Re-run the syntax test multiple times until all warnings are gone.

Builder works by analysing your templates and comparing the ViewHelpers used in the templates to the currently installed versions in each extension containing ViewHelpers (e.g. flux and vhs). This means that you can use this command also to detect problems with any other set of ViewHelpers you may be using, but in this particular case it makes migration a lot easier since you will be presented with these errors without having to test everything manually.

Builder will, by the way, also warn you about syntax problems, for example missing closing tags or misspelled ViewHelper or argument names. It is highly recommended to keep Builder handy when working on Fluid templates - and when building complex Fluid Powered TYPO3 sites, it's pretty much a necessity.

Final words

Same as always: if you are an early adopter and use the Git master versions, which we very much appreciate (you guys provide excellent feedback!) you should be prepared to migrate your templates the next time you pull from masters. We expect to release new versions of flux, fluidpages, fluidcontent and both Bootstrap provider extensions in just a few weeks. While the flux update will be a new major version, neither of the other extensions mentioned are major updates - they are simply adjustments to match the changes made to flux and will be released as minor upgrades depending on at least version 7.0.0 of flux to prevent problems with incomplete upgrades.

The Fluid Powered TYPO3 team.



09/01 2017
09/11 2016
09/06 2016
21/12 2015
07/12 2015
25/11 2015
25/09 2015
22/09 2015
01/08 2015
10/03 2015
03/03 2015
12/02 2015
25/11 2014
01/11 2014
16/10 2014
02/10 2014
02/10 2014
19/09 2014
18/09 2014
05/09 2014
22/08 2014
02/08 2014
27/06 2014
06/06 2014
13/04 2014
27/03 2014
12/03 2014
11/03 2014
05/02 2014
25/01 2014
17/12 2013
08/12 2013
03/12 2013
04/11 2013
Flux 7.0 Teaser
06/08 2013
21/07 2013
10/06 2013
04/06 2013
01/06 2013
27/05 2013
19/05 2013
19/05 2013
11/05 2013
26/04 2013
30/03 2013
19/03 2013
17/03 2013
13/03 2013
10/03 2013
10/03 2013
05/03 2013
04/03 2013
03/03 2013
02/03 2013
01/03 2013
28/02 2013
27/02 2013
25/02 2013
24/02 2013
24/02 2013
23/02 2013
10/02 2013
03/02 2013
03/02 2013
27/01 2013
Asset management in Fluid
20/01 2013
16/01 2013
13/01 2013
08/01 2013
16/12 2012
25/11 2012
18/11 2012
08/11 2012
07/11 2012
05/11 2012
04/11 2012
28/10 2012
22/10 2012
14/10 2012
13/08 2012
08/08 2012
31/07 2012
30/07 2012
25/07 2012
29/04 2012
29/04 2012
22/04 2012
16/04 2012
21/03 2012
Flux 1.4.0 released
08/03 2012
Flux 1.3.0 released
04/03 2012
03/03 2012
28/02 2012
19/02 2012
A Sneaky Sneak Preview of the next version of Flux
13/02 2012
12/02 2012
06/02 2012
30/01 2012
27/01 2012
15/01 2012
26/12 2011
24/12 2011
11/12 2011
11/12 2011
10/12 2011
04/12 2011
04/12 2011
30/11 2011
26/11 2011
25/11 2011