Modifying Fields

Modifying Fields

When composing fields from other fields, some tweaks might need to be made to fit the use case. That might mean modifying the configuration of a field, adding additional fields, or even removing a field.

Modifying a Field's Configuration

The simplest way to modify a field's configuration is to call modifyField, and passing in the name of the field to be modified, and the modified field config as an array. The following example will change the label of a title field:

$fieldsBuilder
    ->modifyField('title', ['label' => 'Headline']);

If the field 'title' doesn't exist, a FieldNotFoundException will be thrown.

Insert Fields After a Particular Field

A more powerful way to modify a field is to pass in a closure instead of a config array to modifyField. The following example will change the label of the title field and add a sub_title field after the title field, but before the content field:

$builder = new FieldsBuilder('Banner');
    $builder
        ->addText('title')
        ->addWysiwyg('content');

    $builder
        ->modifyField('title', function($fieldsBuilder) {
            $fieldsBuilder
                ->setConfig('label', 'Banner Title')
                ->addText('sub_title');

            // Return explicitly, because the `addText` method returns a FieldBuilder (singular)
            // object, not the required FieldsBuilder (plural)
            return $fieldsBuilder;
        })
        ->addTextarea('footnotes');

The closure must accept a new FieldsBuilder object which will have the field 'title' already initialized as the only field. From their, the field's configuration can be modified, as well as fields added after it. This function also must return a FieldsBuilder. The original title field will have its contents replaced with these built fields.

modifyField will return an instance to the original builder, so additional fields can be added after content, in this case a footnotes textarea.

If the closure passed to modifyField doesn't return a FieldsBuilder, a ModifyFieldReturnTypeException will be thrown.

Removing Fields

Simply call removeField and pass in that field's name.

$builder
    ->removeField('title')
    ->addText('headline');

The previous code will remove the title field and then add a new headline field.

Modifying nested fields

Added in 1.12.0 is the ability to modify and remove fields nested in Groups / Repeaters / Flexible Content fields

Say you have repeater but you want to update the width of one of the fields within it. You can do it a couple of ways:

$builder
    ->getField('items')
        ->modifyField('headline', [
            'wrapper' => [
                'width' => '50%'
            ]
        ]);
]);

Alternatively you can use a shorthand method with the -> delimiter to directly reach the field:

$builder
    ->modifyField('items->headline', [
        'wrapper' => [
            'width' => '50%'
        ]
    ]);

To remove a layout from a flexible content field you can:

$builder->getField('sections')->removeLayout('hero');

or

$builder->removeField('sections->hero');

You can also nest as deep as necessary. The following will add a sub title field after the title field in the hero layout of a sections flexible content field.

$builder->modifyField('sections->hero->title', function(FieldsBuilder $fieldsBuilder) {
    $fieldsBuilder->addText('sub_title');
    return $fieldsBuilder;
});

Notes:

You can't modify a Flexible Content field or a FieldsBuilder with a closure, only an array.