toolkit_settings_save_validation

Description

Usage

add_action( 'toolkit_settings_save_validation', 'your_function_name', 10, 2 );

Parameters

$class (mixed)

This parameter is used to hold the class instance that is currently saving settings.

$options (mixed)

This parameter is not directly used by the `toolkit_settings_save_validation` hook itself but is passed by reference from the `ajax_settings_save` method in `src/config.php` and is intended for potential modification or inspection by hooked functions.

Examples

// Example of a function hooked to 'toolkit_settings_save_validation'
// This function will validate specific settings for a hypothetical "Course Progress" module.
function uncanny_toolkit_validate_course_progress_settings( $class, $options ) {
	// Only perform validation if the $class matches our target module.
	if ( 'uncanny-course-progress' === $class ) {
		// Example validation: Ensure 'progress_display_format' is one of the allowed values.
		if ( isset( $options['progress_display_format'] ) && ! in_array( $options['progress_display_format'], array( 'percentage', 'bars', 'list' ) ) ) {
			// If validation fails, we need to communicate this back.
			// Since this is an action hook, and the main saving logic expects a JSON response,
			// we can't directly return an error message here that will be caught by the AJAX handler.
			// A common pattern for action hooks that need to influence the response of a parent AJAX
			// handler is to set a global or use a transient to store error information.
			// For this example, we'll assume the calling AJAX function has a way to check for this.
			// In a real-world scenario, you might pass an error object by reference or use a transient.

			// For demonstration, let's assume we can directly output an error if we can break the flow.
			// In reality, this might be more complex and depend on how Uncanny Toolkit's `ajax_settings_save`
			// is designed to handle errors from this action hook.
			// A better approach would be to have `ajax_settings_save` check a flag set here.

			// To keep it simple for this example, let's simulate an error that the parent function *could* catch.
			// This is a simplification, as direct echoing here would break the JSON response.
			// A more robust solution would involve modifying the $response array directly in the parent function
			// or using a more sophisticated error propagation mechanism.

			// Let's add an error to a (hypothetical) error array that the parent function checks.
			global $uncanny_toolkit_validation_errors;
			if ( ! isset( $uncanny_toolkit_validation_errors ) ) {
				$uncanny_toolkit_validation_errors = array();
			}
			$uncanny_toolkit_validation_errors[ $class ] = __( 'Invalid progress display format selected.', 'uncanny-learndash-toolkit' );
		}

		// Example validation: Ensure 'enable_enrollment_notifications' is a boolean.
		if ( isset( $options['enable_enrollment_notifications'] ) && ! is_bool( $options['enable_enrollment_notifications'] ) ) {
			global $uncanny_toolkit_validation_errors;
			if ( ! isset( $uncanny_toolkit_validation_errors ) ) {
				$uncanny_toolkit_validation_errors = array();
			}
			$uncanny_toolkit_validation_errors[ $class ] = __( 'Invalid value for enabling enrollment notifications.', 'uncanny-learndash-toolkit' );
		}
	}
}

// Add the validation function to the 'toolkit_settings_save_validation' action hook.
// The priority is 10, which is the default.
// The function accepts 2 arguments ($class, $options).
add_action( 'toolkit_settings_save_validation', 'uncanny_toolkit_validate_course_progress_settings', 10, 2 );

// In the `ajax_settings_save()` function of Uncanny Toolkit, after calling `do_action( 'toolkit_settings_save_validation', $class, $options );`,
// it would need to check for the existence of the `$uncanny_toolkit_validation_errors` global variable
// and if it contains any errors for the current $class, it should set $response['error'] to true
// and $response['message'] to the appropriate error message before echoing the JSON.
// For example, within `ajax_settings_save()`:
/*
		// ... after do_action( 'toolkit_settings_save_validation', $class, $options ); ...

		global $uncanny_toolkit_validation_errors;
		if ( isset( $uncanny_toolkit_validation_errors ) && isset( $uncanny_toolkit_validation_errors[ $class ] ) ) {
			$response['error']   = true;
			$response['message'] = $uncanny_toolkit_validation_errors[ $class ];
			echo wp_json_encode( $response );
			wp_die();
		}

		// ... rest of the save logic ...
*/

Placement

This code should be placed in the functions.php file of your active theme, a custom plugin, or using a code snippets plugin.

Source Code

src/config.php:701

public static function ajax_settings_save() {
		// Nonce verification
		if ( ! isset( $_POST['nonce'] ) || ! wp_verify_nonce( $_POST['nonce'], 'uncanny_toolkit' ) ) {
			echo wp_json_encode(
				array(
					'error'   => true,
					'message' => 'Nonce verification failed.',
				)
			);
			wp_die();
		}
		$response = array(
			'error'   => true,
			'message' => '',
		);

		$capability = apply_filters( 'toolkit_settings_save_cap', 'manage_options' );

		if ( ! current_user_can( $capability ) ) {
			echo wp_json_encode(
				array(
					'error'   => true,
					'message' => __( 'You must be an admin to save settings', 'uncanny-learndash-toolkit' ),
				)
			);
			wp_die();
		}

		if ( ! isset( $_POST['class'] ) ) {
			echo wp_json_encode(
				array(
					'error'   => true,
					'message' => __( 'Class for addon is not set', 'uncanny-learndash-toolkit' ),
				)
			);
			wp_die();
		}

		$class   = sanitize_text_field( $_POST['class'] );
		$options = ( isset( $_POST['options'] ) ) ? $_POST['options'] : array();

		// Validate action if any module need some values to set.
		do_action( 'toolkit_settings_save_validation', $class, $options );

		// Delete option and add option are called instead of update option because
		// sometimes update value is equal to the existing value and a false
		// positive is returned

		delete_option( $class );

		$save_settings = add_option( $class, $options );

		$response['error'] = ! $save_settings;

		if ( $save_settings ) {
			$response['message'] = __( 'Settings saved successfully', 'uncanny-learndash-toolkit' );
		} else {
			$response['message'] = __( 'Something went wrong. Please, try again', 'uncanny-learndash-toolkit' );
		}

		echo wp_json_encode( $response );

		wp_die();

	}

Related Hooks

• toolkit_settings_save_cap — fires_nearby