Flux fields

Templating manual

Edit this chapter on Github Jump to...

3.2.4 Flux Fields

You have already seen a few examples of various flux:field.* ViewHelpers being used in templates for pages and content. These ViewHelpers are so-called Flux Form Components - specifically a group of Components which creates definitions of form fields which TYPO3 can render.

As you are already aware, Flux connects records to template files - which is why your Flux fields can be rendered when a particular record is being edited. To illustrate this: Fluidcontent has a special field which selects the "Fluid Content Type". This sets a value in the record that gets saved and when the record is then edited after this, Fluidcontent will use a different template file which may contain different form fields. This is how your template's Flux fields become form fields in TYPO3.

What Flux Form Components are

Internally, TYPO3 expects definitions of forms in an array format known as TCEforms. Such an array can be used to describe the forms for a record - but it can also be used to describe the form structure for a single field in a record. It is this single-field-TCEform concept that is known as FlexForms (the name comes from the TCEforms field type which is called flex). When used to describe a form structure for a single field, TYPO3 will render the TCEforms array as a nested form (where for example, an input field would have been rendered if your TCA specified an input type field instead of a flex type field). To illustrate this: the tt_content.pi_flexform field is a flex type field and we call the form rendered inside this field, a FlexForm.

This array approach often results in huge and very complex structures - and it is this complexity and size which Flux limits by providing a more consistent API to create such definitions. Flux does this by adding two additional layers of API:

  1. The PHP based, object-oriented, hierarchy structure objects located under FluidTYPO3\Flux\Form - these make up the lowest layer of API added by Flux. A hierarchy of objects can then be "built" as TCEforms array which TYPO3 can render.
  2. The ViewHelper layer which uses Fluid ViewHelpers to create and place Flux Form Objects into a hierarchy using the PHP objects from the lower API layer.

The most common API is of course the ViewHelper based API. It is this flavor that allows you to define inside the template, the form fields which can be edited and which when saved become variables which your template can use.

How Flux Form Components work

These components, like TCA and TCEforms, work by nesting - each component type is intended to be used in a specific level - Sheet goes inside Form to create tabs in the form, Field goes inside Sheet or other containers which support fields - namely, Object and Container. A representation of a complete Form structure could be (using pseudo-code):

  • Form (name: 'contacts')
    • Sheet (name: 'manager')
      • Field (type: 'input', label: 'Full name of manager')
      • Field (type: 'select', label: 'Office', items: 'Office A,Office B,Office C')
      • Field (type: 'relation', label: 'Profile page UID', table: 'pages')
        • Wizard (type: 'browse')
    • Sheet (name: 'assistant')
      • Field (type: 'input', label: 'Full name of assistant')
      • Field (type: 'input', label: 'Phone number')
      • Section (label: 'Email addresses')
        • Object (label: 'Email address')
        • Field (type: 'input', label: 'Email address')

This structure, when rendered through TYPO3, will result in:

  1. A form called "Contacts" with two tabs: "Manager" and "Assistant".
  2. A tab called "Manager" with three fields: manager's name, manager's office and manager's personal profile page on the site (if one exists).
  3. A tab called "Assistant" with two fields: assistant's name and assistant's phone number.
  4. A special section with a repeatable object called "email address" which has one field for email address - any number of email addresses can be added and sorted as a list of objects.

How to use Form Component ViewHelpers

Getting access to Flux ViewHelpers in your template is done by including the namespace - examples of which are rendered on each ViewHelper reference landing page and is rendered according to the selected extension version (e.g. Flux below version 7.0.0 renders namespace inclusion examples in the old style, whereas Flux 7.0.0 and above renders in the new style). The namespace is all you need in order to be able to use the ViewHelpers, but depending on what you are creating (page, content, plugin, etc) there may be additional requirements (as an example, Fluidcontent and Fluidpages both require the specially named Configuration section in your template).

Once you grasp the very simple structure requirements (in other words, which components are allowed as children of other components) the question of how to use Flux is mostly related to which arguments should be used and what each argument will do. We have made sure that arguments are consistently named and that each one is clearly documented. Many components even share arguments (name, label, default, etc). Simply follow the structure requirements and build your form by adding any number of components.

The two flavors - PHP and Fluid ViewHelpers - share their argument names and are nested the same way in both flavors. This means that you can use the ViewHelper reference for Flux to learn which arguments are supported by ViewHelpers as well as the corresponding PHP objects. Make sure you select your version of Flux as some property names may change between major versions.

Using the PHP flavor in an IDE naturally gives you code completion and more - in Fluid templates you don't have the same flexibility regarding code completion, but some editors do support the XSD schema features defined in XML standards, in order to provide autocompletion as well as basic validation of syntax and argument types. We made a chapter in this documenation dedicated to Fluid template autocompletion using XSD schema files.

How to use Form Components in PHP

The PHP flavor of the API is considered advanced usage - you can read a lot more about how to use Components and even create your own in the chapter dedicated to custom Form Component usage. Studying these chapters should give you a very clear idea about exactly how much flexibility you gain from custom Form Components. While such Components and PHP usage is not normally necessary, it does allow you to move far beyond what simple ViewHelpers can do, both regarding performance and reusability.

Jump to...