Some of our plugin include a built-in, developer-friendly Settings API that allows you to extend the settings pages with custom tabs, sections, and fields, without modifying the plugin's source code.

The Barn2 Settings API is currently supported by two of our plugins:

• WooCommerce Discount Manager
• Document Library Pro

Hooking into the settings manager

Each supported plugin provides a hook that allows you to inject your custom settings into the settings manager:

barn2_settings_api_{plugin_slug}_boot

Replace {plugin_slug} with the slug of the plugin you're working with. For example:

Plugin Name	Hook Name
Document Library Pro	barn2_settings_api_document-library-pro_boot
WooCommerce Discount Manager	barn2_settings_api_woocommerce-discount-manager_boot

This hook gives you direct access to the Settings_Manager instance used to register tabs, sections, and fields.

Example: Add a custom tab, section, and field

This example adds a new tab to the plugin’s settings page. Inside that tab, it creates a section called “Custom Settings” with one simple text field.

add_action('barn2_settings_api_document-library-pro_boot', __NAMESPACE__ . '\add_custom_settings_tab');

function add_custom_settings_tab($settings_manager) {
    $custom_tab = new \Barn2\Plugin\Document_Library_Pro\Dependencies\Barn2\Settings_API\Tabs\Tab(
        'my_custom_tab',
        __('My Custom Tab', 'your-plugin-textdomain')
    );

    $custom_section = new \Barn2\Plugin\Document_Library_Pro\Dependencies\Barn2\Settings_API\Sections\Section(
        'my_custom_section',
        __('Custom Settings', 'your-plugin-textdomain'),
        __('These are custom settings from an external plugin.', 'your-plugin-textdomain')
    );

    $custom_section->add_field(
        new \Barn2\Plugin\Document_Library_Pro\Dependencies\Barn2\Settings_API\Fields\Text(
            'my_custom_field',
            __('Custom Field', 'your-plugin-textdomain'),
            __('Enter some custom text.', 'your-plugin-textdomain'),
            __('More details shown in tooltip.', 'your-plugin-textdomain'),
            [ 'placeholder' => 'Type here…' ],
            '',
            []
        )
    );

    $custom_tab->add_section($custom_section);
    $settings_manager->add_tabs([$custom_tab]);
}

Note: The example uses the fully qualified class names from the Barn2\Plugin\Document_Library_Pro\Dependencies\Barn2\Settings_API namespace, which is how the Settings API is bundled inside Document Library Pro. If you're integrating with a different plugin or loading the API differently, you may need to adjust the namespace accordingly.

Available field types

• Checkbox
• Checkbox_List
• Multiselect
• Number
• Radio
• Select
• Text
• Textarea
• Toggle

Field constructor parameters

new Field(
    string $name,
    string $label,
    string $description = '',
    string $tooltip = '',
    array $attributes = [],
    mixed $default_value = '',
    array $conditions = []
);

Parameter	Description
$name	Unique identifier for the field.
$label	Label displayed next to the field.
$description	Help text shown below the field.
$tooltip	Tooltip displayed next to the label.
$attributes	HTML attributes (e.g. ['placeholder' => 'Value']).
$default_value	Value used if no saved value exists.
$conditions	Show/hide logic based on other fields.

Note: Individual field types may have additional setters and methods. Refer to the plugin source for details.

Conditional field logic

The Barn2 Settings API supports conditional logic, allowing you to show or hide fields dynamically based on the value of another field.

'conditions' => [
    'rules' => [
        'my_checkbox_field' => [
            'op'    => 'eq',
            'value' => true,
        ]
    ],
    'satisfy' => 'ANY'
]

Rule combination

• 'ANY' – The field is shown if any rule is satisfied.
• 'ALL' – The field is shown only if all rules are satisfied.

Supported operators

Operator	JavaScript Equivalent	Notes
eq	==	Equal
neq, ne	!=	Not equal
gt	>	Greater than
gte	>=	Greater than or equal
lt	<	Less than
lte	<=	Less than or equal
absent	!	Field is not present/empty
empty	!	Alias for absent
present	!!	Field is present and not empty
startsWith	.startsWith()	String starts with value
endsWith	.endsWith()	String ends with value
contains	.includes()	String contains value

Filtering and saving settings

You can customize how settings are saved and respond to when they’ve been saved using the following filters and actions.

barn2_settings_api_{slug}_save_settings

Filter to modify settings before they’re saved.

add_filter( 'barn2_settings_api_my_plugin_save_settings', function ( $settings, $request, $settings_manager, $option_name ) {
    // Modify the settings here.
    return $settings;
}, 10, 4 );

barn2_settings_api_{slug}_settings_saved

Hook that runs after settings are saved.

add_action( 'barn2_settings_api_my_plugin_settings_saved', function ( $settings, $request, $settings_manager, $option_name ) {
    // Do something here.
}, 10, 4 );

Parameters (both hooks):

• array $settings – The saved settings.
• WP_REST_Request $request – The REST request object.
• Settings_Manager $settings_manager – The settings manager instance.
• string $option_name – The option key used in the database.

Settings storage

Settings are stored in a single WordPress option.

Plugin option name slugs

Plugin Name	Option Name Slug
Document Library Pro	document-library-pro_settings
WooCommerce Discount Manager	woocommerce_discount_manager_settings

Accessing settings with the Helper class

Use the Helper class available via the Settings_Manager to read or write settings:

$helper = $settings_manager->get_helper();
$value = $helper->get_option( 'key', 'default' );
$helper->update_option( 'key', 'value' );
$helper->delete_option( 'key' );

Alternatively: use native WordPress functions

$settings = get_option( 'document-library-pro_settings' );
update_option( 'document-library-pro_settings', $settings );
delete_option( 'document-library-pro_settings' );

Related Articles

• Diacritics sorting support
• Templates
• Grid card hooks
• Template functions
• Actions and Filters
• CSS selectors