automator_loops_filter_get_loopable_items

Description

Usage

add_filter( 'automator_loops_filter_get_loopable_items', 'your_function_name', 10, 2 );

Parameters

$loopable_items_array (mixed)

This parameter contains an array that will be populated with loopable items.

$this (mixed)

This parameter contains an array of items that can be iterated over within the loop.

Return Value

The filtered value.

Examples

<?php
/**
 * Example of how to use the 'automator_loops_filter_get_loopable_items' filter.
 *
 * This example demonstrates how to conditionally modify the array of loopable items
 * based on the presence and value of a specific parsed field related to loopable tokens.
 *
 * @param array $loopable_items_array The array of loopable items.
 * @param object $entity_filter_instance The instance of the entity filter object.
 * @return array The modified or original array of loopable items.
 */
add_filter( 'automator_loops_filter_get_loopable_items', function ( $loopable_items_array, $entity_filter_instance ) {

	// Let's assume we want to add a custom item if a specific token value is present.
	// We'll check if a parsed field named 'custom_loop_condition_token' exists
	// and has a truthy value.
	$custom_token_key = '_custom_loop_condition_token'; // Example custom token key
	$custom_token_value_to_trigger = 'enable_special_loop'; // Example value to trigger modification

	if (
		isset( $entity_filter_instance->parsed_fields[ $custom_token_key ] ) &&
		is_string( $entity_filter_instance->parsed_fields[ $custom_token_key ] ) &&
		$entity_filter_instance->parsed_fields[ $custom_token_key ] === $custom_token_value_to_trigger
	) {
		// If the custom token condition is met, add a new item to the loopable items array.
		// This new item could represent a custom data source or an additional option for the loop.
		$loopable_items_array['custom_data_source'] = array(
			'label' => __( 'Special Data Source', 'your-text-domain' ),
			'value' => 'special_source_value',
			// You can add more properties as needed by the Uncanny Automator loops system.
		);
	}

	// Always return the (potentially modified) array.
	return $loopable_items_array;

}, 10, 2 ); // Priority 10, accepts 2 arguments.

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

uncanny-automator-pro/src/core/loops/filter/base/entity-filter-base.php:574
uncanny-automator-pro/src/core/loops/filter/base/entity-filter-base.php:618

public function get_loopable_items() {

		$loopable_items_array = array();

		if ( isset( $this->parsed_fields['_*loopable_tokens'] ) && is_string( $this->parsed_fields['_*loopable_tokens'] ) ) {

			$loopable_token_value = $this->parsed_fields['_*loopable_tokens'];

			// Do not decode falsy values.
			if ( empty( $loopable_token_value ) ) {
				return apply_filters( 'automator_loops_filter_get_loopable_items', $loopable_items_array, $this );
			}

			// Make sure the JSON does not contain any breaking characters.
			$loopable_token_value = str_replace( array( "r", "n" ), array( '\r', '\n' ), $loopable_token_value );

			// Check and fix invalid backslashes.
			$loopable_token_value = preg_replace_callback(
				'/(?<!\\)\\(?![\\/"bfnrtu])/',
				function ( $matches ) {
					return '\\'; // Replace single backslash with double backslash
				},
				$loopable_token_value
			);

			// Decode JSON string to an associative array.
			$loopable_items_array = json_decode( $loopable_token_value, true );

		}

		// Check for JSON decode errors.
		if ( JSON_ERROR_NONE !== json_last_error() ) {

			$json_last_error_msg = json_last_error_msg();

			$log_message = array(
				'$loopable_token_value(raw-from-parse-fields)' => $this->parsed_fields['_*loopable_tokens'],
				'$loopable_token_value(original-string-after-replacements)' => $loopable_token_value,
				'$loopable_items_array(decoded-array)' => $loopable_items_array,
				'json_last_error_msg()'                => $json_last_error_msg,

			);

			automator_log( $log_message, 'Returning the loopable items error.', true, 'loop-error' );

			throw new Loops_Exception( 'Failed to decode JSON: ' . $json_last_error_msg );

		}

		// Handle falsy statements.
		if ( empty( $loopable_items_array ) ) {
			$loopable_items_array = array();
		}

		return apply_filters( 'automator_loops_filter_get_loopable_items', $loopable_items_array, $this );

	}