Re is out: see what's new Lifetime updates on every purchase Support replies within 24 hours Secure checkout via Gumroad 8,500+ sales since 2016

↑↓ Navigate ↵ Open Esc Close

All products
Re:Maily contact form builder is now available on WordPress.org See it live

Editor fields

Updated 3 min read 14 views

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.

Was this article helpful?