Series 5: Sulu for developers Chapter 10 of 16

Custom field types

Development
Applies to: every Sulu website As of Sulu 3.0

In short

A field type is a React component, registered with fieldRegistry.add(). Check the name against the field types of Sulu core first. On the website a PropertyResolver reads the value; if there is none, the default resolver applies.

A field type has two sides. The admin draws the input field, the website receives the stored value. Sulu 3 has a place for both. This chapter shows them with the SuluAdminExtrasBundle, which brings several field types of its own. It is an extension from the Extensions series and serves here as an example project; Sulu itself does not include it.

Helpful first: 5.9 Extending the admin

The field in the admin

A field type is a React component. It receives the properties FieldTypeProps and is registered under a name with fieldRegistry.add(). This name later appears in the attribute type of the template. In the admin, the registration hangs on a hook of the initializer:

From sulu-admin-extras-bundle, src/Resources/js/index.js, shortened javascript
import { initializer } from 'sulu-admin-bundle/services';
import fieldRegistry from 'sulu-admin-bundle/containers/Form/registries/fieldRegistry';
import ColorSelect from './containers/Form/fields/ColorSelect';
import LineBreak from './containers/Form/fields/LineBreak';

initializer.addUpdateConfigHook('sulu_admin_extras', (config, initialized) => {
    if (initialized) {
        return;
    }

    fieldRegistry.add('color_select', ColorSelect);
    fieldRegistry.add('line_break', LineBreak);
});

The smallest component of the bundle is LineBreak. The field shows nothing. It only marks its grid cell in the form so that the following fields move to a new row. The structure is that of every field type: a class with render(), typed as React.Component<FieldTypeProps<...>>:

From containers/Form/fields/LineBreak.js, shortened javascript
import React from 'react';
import type {FieldTypeProps} from 'sulu-admin-bundle/types';

export default class LineBreak extends React.Component<FieldTypeProps<void>> {
    render() {
        return <span ref={this.setMarker} />;
    }
}

The value on the website

What the component passes to onChange is what gets stored. On the website a PropertyResolver reads the value. If there is none for the type, Sulu takes the DefaultPropertyResolver and passes the value to Twig unchanged. A resolver of your own is worth it when the stored value is to be reshaped for Twig. The resolver for color_select, for example, stores primary:#0d6efd and passes only primary to Twig:

From Manuxi\SuluAdminExtrasBundle\Content\Type\ColorSelectPropertyResolver php
class ColorSelectPropertyResolver implements PropertyResolverInterface
{
    public function resolve(mixed $data, string $locale, array $params = []): ContentView
    {
        $value = $data;

        // return only the key ("primary" from "primary:#0d6efd")
        if (\is_string($value) && strpos($value, ':') !== false) {
            $value = explode(':', $value)[0];
        }

        $content = $value ?: '';

        return ContentView::create($content, ['value' => $content]);
    }

    public static function getType(): string
    {
        return 'color_select';
    }
}

getType() must match the name in the admin. ContentView::create() takes the value for content and a list for view. You do not have to tag the service by hand: Sulu registers every class with PropertyResolverInterface by autoconfiguration under the tag sulu_content.property_resolver. If a field refers to other entities, a ResourceLoader (tag sulu_content.resource_loader) also helps, which loads the data in one go.

The field in the template

In the template, the name is the type. The example website uses line_break to put a field on a new row:

From config/templates/includes/groups/config/collection-source.xml html
<property name="display_break" type="line_break"
          visibleCondition="__parent.select_display_source == 'custom'"/>
Bundles without a dependency on AdminExtras

The field types of the AdminExtrasBundle are built for the example website. Standalone bundles such as those for events or testimonials do not require them and get by with the field types of Sulu. Anyone who passes on a bundle should do the same.

More on this

Official documentation