Registering Plugin Settings

Ninja Forms THREE provides a Settings submenu page for registering plugin settings for both the main plugin as well as add-ons. Settings registered with this system will be displayed and saved by Ninja Forms automatically. Creating a separate setting submenu for an add-on will require developing your own process for displaying, processing, and saving settings. Add-ons requiring heavy customization for plugin settings are free to create a new submenu page, but basic settings are easily handled by Ninja Forms.

For more details on the below mentioned WordPress Hooks, see the WordPress Hooks Plugin Settings documentation.

Register Plugin Settings

Individual settings can be added to the master $settings array, underneath a settings group array key. For example:

  • Settings Groups 1
    • Setting A
    • Setting B
  • Settings Group 2
    • Setting C

Settings are configured following the same format as Action Settings and Field Settings. Refer to the Settings Configuration documentation for an example list of setting properties, with descriptions. Note: not all properties are supported.

<?php
function plugin_settings( $settings )
{
$settings[ 'example' ] = array(
'example_setting' => array(
'id' => 'example_setting',
'type' => 'textbox',
'label' => __( 'Example Setting', 'ninja-forms-example' ),
'desc' => __( 'This is an example setting.', 'ninja-forms-example' ),
),
);
return $settings;
}
add_filter( 'ninja_forms_plugin_settings', 'plugin_settings', 10, 1 );

Register Settings Groups

Settings are registered underneath a setting group. A new Settings Group can be created by filtering the $groups array.

Defining a new Settings Group requires a unique id (which should match the array key) and a translatable label.

Each Settings Group is rendered as a metabox on the Ninja Forms Settings submenu page in the WordPress Admin.

<?php
function plugin_settings_groups( $groups )
{
$groups[ 'example' ] = array(
'id' => 'example',
'label' => __( 'Example Settings', 'ninja-forms-example' ),
);
return $groups;
}
add_filter( 'ninja_forms_plugin_settings_groups', 'plugin_settings_groups', 10, 1 );

Checking Setting Values

Hook: ninja_forms_check_setting_{$id}

Example: ninja_forms_check_setting_example_setting

Each time the Ninja Forms Settings submenu page is loaded, a WordPress filter hook is fired for every setting. This filter hook allows for add-ons to check (validate) the value of each setting. When checking or validating a setting’s value, the setting can be updated with errors before being passed back through the filter.

Errors added to a setting will display an Admin Notice at the top of the Settings submenu page, which links to an inline error displayed below the appropriate setting.

An error can be added as a translatable string to the $setting[ ‘error’ ] array item (Note: array key is NOT required, only the value).

<?php
function check_example_setting( $setting )
{
// Check for errors…
if( $has_errors ) {
$setting['errors'][] = __('The value that you have entered appears to be invalid.', 'ninja-forms-example');
}
return $setting;
}
add_filter( 'ninja_forms_check_setting_example_setting', 'check_example_setting', 10, 1 );

Updating Setting’s Values

Hook: ninja_forms_update_setting_{$id}

Example: ninja_forms_update_setting_example_setting

Before a setting’s value is saved, the value is first sanitized, the filtered.

<?php
function update_example_setting( $setting_value )
{
$setting_value = trim( $setting_value );
return $setting;
}
add_filter( 'ninja_forms_update_setting_example_setting', 'update_example_setting', 10, 1 );

Saving Setting’s Values

Hook: ninja_forms_save_setting_{$id}

Example: ninja_forms_save_setting_example_setting

After a setting’s value has been saved, a WordPress Action Hook is triggered, passing the setting’s value, for further processing.

<?php
function save_example_setting( $setting_value )
{
if( strpos( $setting_value, '_' ) ){
$parts = explode( '_', $setting_value );
foreach( $parts as $key => $value ){
Ninja_Forms()->update_setting( 'example_part_' . $key, $value );
}
}
}
add_action( 'ninja_forms_save_setting_example_setting', 'save_example_setting', 10, 1 );

Full Code Example

The following example organizes all of the add-on related Ninja Forms Settings hooks inside of a dedicated plugin settings class:

<?php if ( ! defined( 'ABSPATH' ) ) exit;
/**
* Class NF_Example_Admin_Settings
*
* This is an example implementation of a Settings Class for a Ninja Forms Add-on.
* The Ninja Forms Settings Submenu page handles registering, rendering, and saving settings.
* Settings handled by Ninja Forms can be access using the Ninja Forms API.
* Multiple WordPress Hooks are available for interacting with settings processing.
*/
final class NF_Example_Admin_Settings
{
/**
* NF_Example_Admin_Settings constructor.
*
* The following WordPress hooks are listed in processing order.
*/
public function __construct()
{
/*
* On Settings Page Load
*/
add_filter( 'ninja_forms_plugin_settings', array( $this, 'plugin_settings' ), 10, 1 );
add_filter( 'ninja_forms_plugin_settings_groups', array( $this, 'plugin_settings_groups' ), 10, 1 );
add_filter( 'ninja_forms_check_setting_example_setting', array( $this, 'check_example_setting' ), 10, 1 );
/*
* On Settings Page Save (Submit)
*/
add_filter( 'ninja_forms_update_setting_example_setting', array( $this, 'update_example_setting' ), 10, 1 );
add_action( 'ninja_forms_save_setting_example_setting', array( $this, 'save_example_setting' ), 10, 1 );
}
/**
* Add Plugin Settings
*
* Add a new setting within a defined setting group.
* The setting's configuration is similar to Action Settings and Fields Settings.
*
* @param array $settings
* @return array $settings
*/
public function plugin_settings( $settings )
{
$settings[ 'example' ] = array(
'example_setting' => array(
'id' => 'example_setting',
'type' => 'textbox',
'label' => __( 'Example Setting', 'ninja-forms-example' ),
'desc' => __( 'This is an example setting.', 'ninja-forms-example' ),
),
);
return $settings;
}
/**
* Add Plugin Settings Groups
*
* Add a new Settings Groups for this plugin's settings.
* The grouped settings will be rendered as a metabox in the Ninja Forms Settings Submenu page.
*
* @param array $groups
* @return array $groups
*/
public function plugin_settings_groups( $groups )
{
$groups[ 'example' ] = array(
'id' => 'example',
'label' => __( 'Example Settings', 'ninja-forms-example' ),
);
return $groups;
}
/**
* Check Example Setting for Errors
*
* Before the Example Setting is disaplyed, check for / add errors for display.
* Note: This check is performed when the Ninja Forms Settings Submenu page is loaded.
*
* @param array $setting
* @return array $setting
*/
public function check_example_setting( $setting )
{
if( $has_errors ) {
$setting['errors'][] = __('The value you have entered appears to be invalid.', 'ninja-forms-example');
}
return $setting;
}
/**
* Update Example Setting Value
*
* Before the Example Setting is saved, update the value.
*
* @param $setting
* @return mixed
*/
public function update_example_setting( $setting_value )
{
$setting_value = trim( $setting_value );
return $setting_value;
}
/**
* Save Example Setting
*
* After the Example Setting is saved, do something with the saved value.
*
* @param $setting
* @return void
*/
public function save_example_setting( $setting_value )
{
if( strpos( $setting_value, '_' ) ){
$parts = explode( '_', $setting_value );
foreach( $parts as $key => $value ){
Ninja_Forms()->update_setting( 'example_part_' . $key, $value );
}
}
}
} // End Class NF_Example_Admin_Settings