Editor fields
The layout editor’s sidebar can take sections and fields of your own, new options in its built-in selects, and changes to how a built-in field looks.
Add a section
forma_controls adds sections with the same field types as a skin’s settings.php. This one adds an Overlay toggle after the Skin section, shown only while the Work 1 style is chosen:
add_filter( 'forma_controls', function ( $controls ) {
$controls['my_card'] = [
'title' => __( 'Card extras', 'my-theme' ),
'after' => 'skin',
'condition' => [ 'skin' => 'work-1' ],
'fields' => [
'overlay' => [ 'type' => 'toggle', 'label' => __( 'Overlay', 'my-theme' ), 'default' => true, 'class' => 'has-overlay' ],
],
];
return $controls;
} );
The toggle has class, so the grid gets has-overlay while it is on and your CSS can use it. Without class, read the value in a template from $config['extra'][ section ][ field ]:
<?php if ( ! empty( $config['extra']['my_card']['overlay'] ) ) : ?>
<span class="work-card__overlay"></span>
<?php endif; ?>
'after' => 'skin' places the section after the Skin section; 'panel' => 'skin' puts its fields inside it instead.
Add a field to a built-in card style
The same filter gets every skin’s settings.php as a section named skin_{id}, so a child theme or plugin can add to it:
add_filter( 'forma_controls', function ( $controls ) {
$controls['skin_fade']['fields']['show']['fields']['excerpt'] = [ 'type' => 'toggle', 'label' => __( 'Show the excerpt', 'my-theme' ) ];
return $controls;
} );
forma_image_controls adds fields to each image of a Media Library source. Their values are in $item['extra'].
Add options to a built-in select
forma_select_options takes the select by its config path. The editor lists the new options after the built-in ones, and saving keeps them, so no other PHP is needed:
add_filter( 'forma_select_options', function ( $options ) {
$options['layout.slider.effect']['cards'] = __( 'Cards', 'my-theme' );
$options['click.action']['quickview'] = __( 'Quick view', 'my-theme' );
return $options;
} );
The path is the setting’s place in the layout config: click.action is $config['click']['action'] in PHP. Forma doesn’t know what a new option means, so your theme acts on it, for example in a template or in forma_item_data or forma_container_attributes. The paths are listed in Developer reference → Config paths.
Change a built-in field
The forma.field JavaScript filter gets each built-in field’s props and its path. It can change the label, help, options, min, max or disabled state, and returning false hides the field.
// functions.php: load the script in the editor
add_action( 'enqueue_block_editor_assets', function () {
wp_enqueue_script( 'my-theme-forma', get_theme_file_uri( 'js/forma-editor.js' ), [ 'wp-hooks' ], '1.0', true );
} );
// js/forma-editor.js
wp.hooks.addFilter( 'forma.field', 'my-theme', ( props, path ) => {
if ( 'layout.slider.speed' === path ) {
return { ...props, max: 6000, help: 'Slow slides suit large photos.' };
}
// Hide the Loop toggle
return 'layout.slider.loop' === path ? false : props;
} );
Saving still checks a value against the field’s built-in range. Use forma.field for how a field looks, and forma_select_options for new choices.