Filter uncanny-automator

uap_option_all_ld_topics

Filters the list of all Learndash topics before they are displayed, allowing modification of the options.

add_filter( 'uap_option_all_ld_topics', $callback, 10, 1 );

Description

This filter hook, `uap_option_all_ld_topics`, fires when Uncanny Automator is preparing to display LearnDash topics in a select field. Developers can use this hook to modify the options array for the select field. This allows for custom filtering or manipulation of the available LearnDash topics presented to the user within an Uncanny Automator automation.

Usage

add_filter( 'uap_option_all_ld_topics', 'your_function_name', 10, 1 );

Parameters

$option (mixed): This parameter, named `$option`, holds the value of the option being filtered, which in this context, likely represents the output of the `all_ld_topics` method, possibly an array of Learndash topics.

Return Value

The filtered value.

Examples

<?php
/**
 * Example of how to use the uap_option_all_ld_topics filter.
 * This example modifies the 'options' array to add a custom placeholder
 * for users to select a specific topic if available, or to enter a custom ID.
 */
add_filter( 'uap_option_all_ld_topics', 'my_custom_ld_topics_options', 10, 1 );

function my_custom_ld_topics_options( $option ) {

	// Check if we have existing options and if they are in a usable format
	if ( ! isset( $option['options'] ) || ! is_array( $option['options'] ) ) {
		// If not, we can't proceed with adding custom options safely
		return $option;
	}

	// Add a new option to allow users to select "Any LearnDash Topic"
	// This is useful for triggers that don't need a specific topic.
	$custom_options = array(
		'' => esc_html__( 'Any LearnDash Topic', 'your-text-domain' ),
	);

	// Merge the custom option with the existing LearnDash topics
	$option['options'] = array_merge( $custom_options, $option['options'] );

	// Optionally, you could also modify the relevant_tokens or descriptions
	// based on the presence of this new option or other logic.

	return $option;
}

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/integrations/learndash/helpers/learndash-helpers.php:392

public function all_ld_topics( $label = null, $option_code = 'LDTOPIC' ) {

		if ( ! $label ) {
			$label = esc_attr_x( 'Topic', 'Learndash', 'uncanny-automator' );
		}

		$args = array(
			'post_type'      => 'sfwd-topic',
			'posts_per_page' => 9999, // phpcs:ignore WordPress.WP.PostsPerPage.posts_per_page_posts_per_page
			'orderby'        => 'title',
			'order'          => 'ASC',
			'post_status'    => 'publish',
		);

		$options = Automator()->helpers->recipe->options->wp_query( $args, true, esc_attr_x( 'Any topic', 'Learndash', 'uncanny-automator' ) );

		$option = array(
			'option_code'              => $option_code,
			'label'                    => $label,
			'input_type'               => 'select',
			'required'                 => true,
			'options'                  => $options,
			'relevant_tokens'          => wp_list_pluck( $this->get_topic_relevant_tokens( 'trigger', $option_code ), 'name' ),
			'custom_value_description' => esc_html_x( 'Topic ID', 'LearnDash', 'uncanny-automator' ),
		);

		return apply_filters( 'uap_option_all_ld_topics', $option );
	}