Settings tabs, field types and user preferences

Addofy's settings page is made of tabs. Your plugin can add a tab, register new field types for module settings, and store preferences per user.

Add a settings tab

Add a tab with the adba_settings_tabs filter. Extend AbstractTab: it gives the default capability (manage_options) and form(), which wraps your fields in the Addofy form with the nonce and the save button.

Addofy adds the submenu entry and checks the capability and the nonce before save() runs.

final class My_Tab extends \AddoBack\Modules\Settings\AbstractTab {
	public function id(): string { return 'myplugin'; }
	public function label(): string { return __( 'My plugin', 'myplugin' ); }
	public function render(): string {
		$value = (string) get_option( 'myplugin_greeting', '' );
		return $this->form( '<p><label>' . esc_html__( 'Greeting', 'myplugin' ) . ' <input name="adba[greeting]" value="' . esc_attr( $value ) . '"></label></p>' );
	}
	public function save( array $input ): array {
		update_option( 'myplugin_greeting', sanitize_text_field( (string) ( $input['greeting'] ?? '' ) ) );
		return array( 'notice' => 'saved', 'args' => array() );
	}
}

add_filter( 'adba_settings_tabs', static function ( array $tabs ) {
	$tabs['myplugin'] = new My_Tab();
	return $tabs;
} );

Use the id of a built-in tab (modules, visibility, menu, views, preferences, tools) to replace it. Built-in tabs can be moved but not removed. The ids did not change in 2.30: visibility is labelled Access and preferences is labelled Appearance.

The adba_settings_merged_tabs filter shows a tab inside another one, as tab id => host tab id. By default views shows at the bottom of visibility. Remove that entry to give Views its own place in the tab bar again.

Module settings in a panel

The Modules tab shows only the switches. The Settings button on a module opens the fields of its settings_schema() in a panel, or as a page of its own without JavaScript. Give a field a priority to set its place: lower comes first, the default is 10 and equal values keep the declared order.

'limit' => array(
	'type'     => 'number',
	'label'    => __( 'Rows', 'myplugin' ),
	'default'  => 5,
	'priority' => 5,
),

Settings of the Appearance tab that belong to a module show in that module's panel. The adba_settings_panel_keys filter maps a config key to a module id; remove a key to show it on Appearance again. Where a setting is stored does not change.

Make your settings searchable

Search settings and the command palette find every field of a module schema by itself, and a tab of your own by its name. Add the single settings of your own tab with adba_settings_index. Each entry needs a label and a url; add #id of the row to the url to mark it.

add_filter( 'adba_settings_index', static function ( array $entries ) {
	$entries[] = array(
		'key'         => 'myplugin_greeting',
		'label'       => __( 'Greeting', 'myplugin' ),
		'description' => __( 'Text above the dashboard.', 'myplugin' ),
		'place'       => __( 'My plugin', 'myplugin' ),
		'url'         => \AddoBack\Modules\Settings\Page::url( 'myplugin' ) . '#myplugin-greeting',
	);
	return $entries;
} );

Register a field type

Register a field type on the adba_register_fields action:

add_action( 'adba_register_fields', static function ( $schema ) {
	$schema->register_field( new My_Field() );
} );

Registering an existing type replaces it: the last registration wins. The text type always remains as the fallback.

User preferences

Register a preference, then read and write it like Addofy's own:

add_filter( 'adba_user_prefs', static function ( array $prefs ) {
	$prefs['myplugin_layout'] = array( 'values' => array( 'grid', 'list' ), 'default' => 'list' );
	$prefs['myplugin_tips']   = array( 'values' => 'bool', 'default' => true );
	return $prefs;
} );

adba.prefs.set( 'myplugin_layout', 'grid' ); // Saved to user meta, synced to other tabs.
adba.prefs.get( 'myplugin_layout', 'list' );

Keys need your plugin prefix. Addofy's own keys (theme, density, mode, focus, shortcuts, guides_on) cannot be redefined.

In PHP, the service prefs has effective(), stored(), defaults(), update() and extension_defs(). Store::extension_prefs() still works but is deprecated; Store::all_prefs() was removed in 2.34.0.

Related

• Writing a module
• Settings and quick start hooks