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, for example:

global $post;
$post_id = $post->ID;

$post_id = get_the_ID();
$post_url = get_the_permalink();

Another feature that makes this hook very powerful is that you can use built-in and custom dynamic tags within it. The built-in tags get post properties like the URL or title. Custom dynamic tags can get content from other (hidden) builder items, which gives you access to content from custom fields:

// built-in dynamic tags
{{ post:id }} // Returns the post’s id
{{ post:name }} // Returns the post’s name (slug)
{{ post:type }} // Returns the post’s type
{{ post:title }} // Returns the post’s title
{{ post:url }} // Returns the post’s url
{{ post:image }} // Returns the post’s featured image (in "full”" size).

// custom dynamic tags
{{ my-builder-item-name }}

Check out the example below to see how to implement these dynamic tags.

Examples

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

Limit a builder item to a number of characters

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

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

Be aware that the above example can cause problems if the excerpt string contains HTML. The substr function trims to the set number of characters. It does not recognize HTML and could leave broken HTML tags.

If you have HTML in your excerpts, you could also use wp_trim_words to trim the item to a specific number of words:

Limit a builder item to a number of words

This example selects a builder item by name and limits its output to 8 words (not characters) with the wp_trim_words function. It uses the third parameter of this function to append an ellipsis between parentheses (…) after the last word:

add_filter( 'facetwp_builder_item_value', function( $value, $item ) {
  if ( 'my-excerpt' == $item['settings']['name'] ) {
    $length = 8; // set the number of words
    $more =  ' (…)'; // append an ellipsis between parentheses (…) after the last word
    $value = wp_trim_words( $value, $length, $more );
  } 
  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 );

Some builder item types have their own “Link” setting to link them to the post URL (or a custom URL), but others, like the ones made from Advanced Custom Fields or Pods custom fields, do not. This hook can be used to add a link to those kinds of items.

The following example adds a link to the builder item with the name my-item-name:

<?php
// replace 'my-item-name' with the name of your builder item
add_filter( 'facetwp_builder_item_value', function( $value, $item ) {
  if($item['settings']['name'] == 'my-item-name') {
    return '<a href="' . get_permalink() . '">' . $value . '</a>';
  }
  return $value;
}, 10, 2 );

Within the hook you can also access other post properties. You could for example retrieve the post ID with get_the_ID() in order to link each item to an external website with the post ID as part of the link:

<?php
// replace 'my-item-name' with the name of your builder item
add_filter( 'facetwp_builder_item_value', function( $value, $item ) {
  if ( $item['settings']['name'] == 'my-item-name' ) {
    return '<a href="https://my-other-website.com/products/' . get_the_ID() . '" target="_blank" rel="nofollow noopener">' . $value . '</a>';
  }
  return $value;
}, 10, 2 );

Use dynamic tags

The following example demonstrates how to use dynamic tags within this hook. In this case we used two types of tags: a built-in dynamic tag, {{ post:url }}, which generates the post URL in the href attribute. And a custom dynamic tag, {{ my-item-price }}, made from a separate (hidden) builder item by that name, which retrieves the price from a custom field. The resulting output is a link to the post URL with the link text containing the value of the my-item-name builder item (which could be the post title), plus the price.

<?php
// replace 'my-item-name' and 'my-item-price' with the names of your builder items
add_filter( 'facetwp_builder_item_value', function( $value, $item ) {
  if($item['settings']['name'] == 'my-item-name') {
    return '<a href="{{ post:url }}">' . $value . ' - $ {{ my-item-price }}</a>';
  }
  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:

<?php
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