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.
Series 5: Sulu for developers Chapter 10 of 16
Custom field types
In short
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:
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<...>>:
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} />;
}
}
Sulu core registers its field types before those of the bundles. If you use a name twice, fieldRegistry.add() throws an error (“has already been used for another field”), and the form does not render or shows the core type. Search for the name first in vendor/sulu/sulu/src/Sulu/Bundle/AdminBundle/Resources/js/index.js (constants FIELD_TYPE_*) and in assets/admin/node_modules/sulu-*-bundle. The type single_icon_selection was such a case: Sulu has it itself. The AdminExtrasBundle therefore replaces the entry in fieldRegistry.fields directly instead of calling add().
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:
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:
<property name="display_break" type="line_break"
visibleCondition="__parent.select_display_source == 'custom'"/>
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.