/facets

DescriptionDescription

This filter is called when fetching facets in the admin interface and on the frontend to display facets and query content.

It allows to add your own facets with your own logic. Creating custom facets requires advanced knowledge in PHP and SQL languages.

ArgumentsArguments

ArgumentTypeDescription
$facetsarrayHolds registered facet arguments

ExampleExample

PHP
functions.php
function prefix_register_facet( $facets ) {
	
	// 'my_facet' corresponds to the facet slug.
	$facets['my_facet'] = [
		'name'  => __( 'My Facet', 'text-dmain' ),
		'type'  => 'filter',
		'class' => 'My_Facet_Class',
	];

	return $facets;
	
}

add_filter( 'wp_grid_builder/facets', 'prefix_register_facet', 10, 1 );

The plugin will use the following methods, if available, from your facet class:

  • query_facet: To query facet values/names depending of content and filter state.
  • render_facet: To display facet values/names queried by query_facet method.
  • query_objects: To filter content by querying object ids (post ids, term ids or user ids) from selected facet values.

As example, this facet class allows to create an alphabetical list to filter content by first letter:

PHP
functions.php
/**
 * Alphabetical Facet class example
 *
 * @class My_Facet_Class
 * @since 1.0.0
 */
class My_Facet_Class {

	/**
	 * Constructor
	 *
	 * @access public
	 */
	public function __construct() {}

	/**
	 * Query facet choices
	 *
	 * @access public
	 *
	 * @param array $facet Holds facet settings.
	 * @return array Holds facet items.
	 */
	public function query_facet( $facet ) {

		global $wpdb;

		$where_clause = wpgb_get_where_clause( $facet );

		// We query facet_name distinctly by the first letter.
		// In this example, we do not use the facet_value because depending of its length it may be encoded (md5).
		$facet_names = $wpdb->get_col(
			$wpdb->prepare(
				"SELECT DISTINCT UPPER(LEFT(facet_name, 1)) AS letter
				FROM {$wpdb->prefix}wpgb_index
				WHERE slug = %s
				AND $where_clause
				GROUP BY letter",
				$facet['slug']
			)
		); // WPCS: unprepared SQL ok.

		return $facet_names;

	}

	/**
	 * Render facet choices
	 *
	 * @access public
	 *
	 * @param array $facet Holds facet settings.
	 * @param array $items Holds facet items.
	 * @return string Facet markup.
	 */
	public function render_facet( $facet, $items ) {

		$output  = '<div class="wpgb-alphabetical-facet">';
		$output .= '<ul class="wpgb-inline-list">';
		$output .= $this->render_letters( $facet, $items );
		$output .= '</ul>';
		$output .= '</div>';

		return $output;

	}

	/**
	 * Render letter buttons
	 *
	 * @access public
	 *
	 * @param array $facet Holds facet settings.
	 * @param array $items Holds facet items.
	 * @return string Letter buttons markup.
	 */
	public function render_letters( $facet, $items ) {

		$output  = '';
		$letters = str_split( 'ABCDEFGHIJKLMNOPQRSTUVWXYZ' );

		foreach ( $letters as $letter ) {
			$output .= '<li>' . $this->render_button( $facet, $items, $letter ) . '</li>';
		}

		return $output;

	}

	/**
	 * Render letter button
	 *
	 * @access public
	 *
	 * @param array  $facet Holds facet settings.
	 * @param array  $items Holds facet items.
	 * @param string $letter Current letter.
	 * @return string Letter button markup.
	 */
	public function render_button( $facet, $items, $letter ) {

		$checked  = in_array( $letter, $facet['selected'], true );
		$disabled = ! in_array( $letter, (array) $items, true );
		$pressed  = $checked ? 'true' : 'false';
		$tabindex = $disabled ? -1 : 0;

		$output  = '<div class="wpgb-button" role="button" aria-pressed="' . esc_attr( $pressed ) . '" tabindex="' . esc_attr( $tabindex ) . '">';
		$output .= '<input type="hidden" name="' . esc_attr( $facet['slug'] ) . '" value="' . esc_attr( $letter ) . '"' . disabled( $disabled, true, false ) . '>';
		$output .= '<span class="wpgb-button-label">' . esc_html( $letter ) . '</span>';
		$output .= '</div>';

		return $output;

	}

	/**
	 * Query object ids (post, user, term) for selected facet values
	 *
	 * @since 1.0.0
	 * @access public
	 *
	 * @param array $facet Holds facet settings.
	 * @return array Holds queried facet object ids.
	 */
	public function query_objects( $facet ) {

		global $wpdb;

		$placeholders = rtrim( str_repeat( '%s,', count( $facet['selected'] ) ), ',' );

		// We query object ids that match selected letter(s) from index table.
		$object_ids = $wpdb->get_col(
			$wpdb->prepare(
				"SELECT DISTINCT object_id
				FROM {$wpdb->prefix}wpgb_index
				WHERE slug = %s
				AND UPPER(LEFT(facet_name, 1)) IN ($placeholders)",
				array_merge( (array) $facet['slug'], $facet['selected'] )
			)
		); // WPCS: unprepared SQL ok.

		return $object_ids;

	}
}