Overview

This filter lets you modify the output value of a Listing Builder item.

Parameters

  • $value | mixed | The item value
  • $item | array | An associative array of item data:
$item = [
    'source' => 'cf/photo_url',
    'settings' => [
        'prefix' => '',
        'suffix' => '',
        'is_hidden' => false,
        'name' => 'photo_url',
        'css_class' => '',
        /* other settings based on the item type */
    ]
];

Within this hook, you also have access to the current post, e.g.

global $post;

$post_id = $post->ID;

Examples

Below are a few examples that show how versatile this hook makes the Listing Builder, and how creative you can get.

Limit a Post Excerpt item to 120 characters and add ellipsis

This example takes a Post Excerpt builder item, limits its output to 120 characters, and appends an ellipsis (…) to the end:

add_filter( 'facetwp_builder_item_value', function( $value, $item ) {
  if ( 'post_excerpt' == $item['source'] ) {
    $value = substr( $value, 0, 120 ).' (…)';
  }
  return $value;
}, 10, 2 );

Change the date format from a custom field

The following example takes the value from a builder item made from a custom field with a date/time string, and changes the format:

add_filter( 'facetwp_builder_item_value', function( $value, $item ) {
  if ( 'date-field' == $item['settings']['name'] ) {
    $value = date_create( $value );
    $value = date_format( $value, "d-m-Y" );
  }
  return $value;
}, 10, 2 );

Output an array as a comma-separated string

This example outputs a comma-delimited list from a builder item made from an ACF field saved as an array:

add_filter( 'facetwp_builder_item_value', function( $value, $item ) {
  if ( 'acf/my_field' == $item['source'] ) {
    if ( is_array( $value ) && ! empty( $value ) ) {
      return implode( ', ', $value ); // ', ' - the delimiter can be changed to other characters or even html
    } else {
      return '';
    }
  }
  return $value;
}, 10, 2 );

Output a simple HTML5 audio player from a file upload field

This creative example outputs a simple HTML5 audio / mp3 player using a builder item made from an ACF file upload field:

add_filter( 'facetwp_builder_item_value', function( $value, $item ) {
  if ( 'mp3-preview' == $item['settings']['name'] ) {
    if ( is_array( $value ) && ! empty( $value['url'] ) ) {
      $src   = $value['url'];
      $value = '<audio controls>';
      $value .= '<source src="' . $src . '" type="audio/mpeg">';
      $value .= 'Your browser does not support the audio element.';
      $value .= '</audio>';
    }
  }
  return $value;
}, 10, 2 );

More examples

See also