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')
    ->setRequestUpdate(TRUE)
    ->setValidate('trim,int')
$form->add($field);
$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 (

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 -

github.com/FluidTYPO3/builder

or

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.


Cheers,
The Fluid Powered TYPO3 team.