tincanny_row_data

Description

Usage

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

Parameters

$_row (mixed)

This parameter contains an object representing a single row of data for the Tin Can report.

Return Value

The filtered value.

Examples

add_filter( 'tincanny_row_data', 'my_custom_tincanny_row_data_modifier', 10, 1 );

/**
 * Modify Uncanny Tin Can row data to add or alter specific fields.
 *
 * This example demonstrates how to add a new column to the Uncanny Tin Can report
 * and modify an existing one.
 *
 * @param array $row_data An array representing a single row of the Tin Can report data.
 *                       Expected keys include: 'group_name', 'user_name', 'course_name',
 *                       'module_name', 'target_name', 'verb', 'result', 'completion', 'xstored'.
 * @return array The modified row data.
 */
function my_custom_tincanny_row_data_modifier( $row_data ) {
	// --- Example 1: Add a new column for the completion percentage if 'result' is available ---
	if ( isset( $row_data['result'] ) && ! empty( $row_data['result'] ) ) {
		// Assuming 'result' might be in a format like "X / Y" or just a score.
		// We'll try to extract the score and the minimum if present.
		$score = null;
		$minimum = null;

		if ( strpos( $row_data['result'], '/' ) !== false ) {
			list( $score_part, $minimum_part ) = explode( '/', $row_data['result'], 2 );
			$score   = floatval( trim( $score_part ) );
			$minimum = floatval( trim( $minimum_part ) );
		} elseif ( is_numeric( $row_data['result'] ) ) {
			$score = floatval( $row_data['result'] );
		}

		// Calculate completion percentage if we have both score and minimum.
		if ( $score !== null && $minimum !== null && $minimum > 0 ) {
			$completion_percentage = round( ( $score / $minimum ) * 100, 2 );
			$row_data['completion_percentage'] = "{$completion_percentage}%";
		} elseif ( $score !== null && $minimum === null ) {
			// If only a score is present, we can't calculate a percentage accurately.
			// We might still want to indicate if there was a score recorded.
			$row_data['completion_percentage'] = 'N/A (No minimum)';
		} else {
			$row_data['completion_percentage'] = 'N/A';
		}
	} else {
		$row_data['completion_percentage'] = 'N/A';
	}

	// --- Example 2: Modify the 'course_name' to prepend a category if it exists ---
	// This assumes that the original 'course_name' might contain category information
	// that we want to highlight or make more prominent.
	if ( isset( $row_data['course_name'] ) && ! empty( $row_data['course_name'] ) ) {
		// In a real scenario, you might fetch this category from post meta or a custom field.
		// For this example, we'll simulate finding a category.
		$course_id = null; // You would need to get the course ID if available in $row_data
		// Example: $course_id = $row_data['course_id']; // if course_id is part of the row data

		$course_category_prefix = '';
		if ( $course_id ) {
			// Simulate fetching a category. Replace with actual WordPress query if needed.
			// $course_category = get_the_terms( $course_id, 'course_category' ); // Example category taxonomy
			// if ( ! is_wp_error( $course_category ) && ! empty( $course_category ) ) {
			//     $course_category_prefix = '[' . $course_category[0]->name . '] ';
			// }
			if ( str_contains( $row_data['course_name'], 'Advanced' ) ) {
				$course_category_prefix = '[Advanced] ';
			} elseif ( str_contains( $row_data['course_name'], 'Beginner' ) ) {
				$course_category_prefix = '[Introductory] ';
			}
		}
		$row_data['course_name'] = $course_category_prefix . $row_data['course_name'];
	}

	// --- Example 3: Make the 'verb' case-insensitive in display ---
	if ( isset( $row_data['verb'] ) && ! empty( $row_data['verb'] ) ) {
		// The source context already uses ucfirst, but this ensures it if the filter is applied earlier.
		$row_data['verb'] = ucfirst( strtolower( $row_data['verb'] ) );
	}

	return $row_data;
}

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/uncanny-tincan/classes/Database/Admin.php:229
src/uncanny-tincan/classes/Database/Admin.php:528

public function build_tincan_report_data( $data ) {
		$is_csv  = $this->filters['is_csv'] ?? false; // Check if CSV export is enabled
		$results = array();
		foreach ( $data as $row ) {
			$result   = $row->result;
			$site_url = site_url();

			if ( ! is_null( $row->result ) && $row->minimum ) {
				$result = $row->result . ' / ' . $row->minimum;
			}

			$completion = '';

			if ( ! is_null( $row->result ) ) {
				$completion = ( $row->result > 0 ) ? '<span class="dashicons dashicons-yes"></span>' : '<span class="dashicons dashicons-no"></span>';
			}

			$_row = array(
				'group_name'  => ! empty( $row->group_name ) ? sprintf( '<a href="%s" target="_blank">%s</a>', TinCannyShortcode::make_absolute( $row->group_id, $site_url ), $row->group_name ) : 'n/a',
				'user_name'   => sprintf( '<a href="%s" target="_blank">%s</a>', admin_url( "user-edit.php?user_id={$row->user_id}" ), $row->user_name ),
				'course_name' => ! empty( $row->course_name ) ? $row->course_name : 'n/a',
				'module_name' => sprintf( '<a href="%s" target="_blank">%s</a>', TinCannyShortcode::make_absolute( $row->module, $site_url ), $row->module_name ),
				'target_name' => sprintf( '<a href="%s" target="_blank">%s</a>', TinCannyShortcode::make_absolute( $row->target, $site_url ), $row->target_name ),
				'verb'        => ucfirst( $row->verb ),
				'result'      => '<span class="tclr-reporting-datatable__no-wrap">' . $result . '</span>',
				'completion'  => $completion,
				'xstored'     => $row->xstored,
			);

			$_row = apply_filters( 'tincanny_row_data', $_row );

			// Clean up HTML if exporting to CSV
			if ( $is_csv ) {
				$_row = array_map( function ( $value ) {
					if ( is_string( $value ) ) {
						// Strip HTML tags and decode special characters
						return html_entity_decode( wp_strip_all_tags( $value ) );
					}

					return $value;
				}, $_row );
			}

			$results[] = $_row;
		}

		return $results;
	}