Templating

To integrate aggregations into your search template, there are some helper functions that can be used to output an aggregation as a list of checkboxes or as a select control inside of your search form. Additionally, if you need to control the aggregation's output more strictly than what is possible with the default output, you can work directly with the aggregation object, which has a list of aggregation buckets with properties (count, key, label, selected) which can be used to create a custom form control or to populate an API response.

Getting an Aggregation

In order to get an aggregation, you need to query it based on its label or its query var. For example, the post type aggregation has a query var of post_type, and taxonomy aggregations have a query var of taxonomy_{$taxonomy_name}, such as taxonomy_category.

get_aggregation_by_label

Returns an Elasticsearch_Extensions\Aggregations\Aggregation object based on the aggregation's human-readable label.

Usage

elasticsearch_extensions()->get_aggregation_by_label( string $label )

Parameters

$label

(string) The human-readable label for the aggregation.

Example

$post_type_aggregation = elasticsearch_extensions()->get_aggregation_by_label( 'Content Type' );

get_aggregation_by_query_var

Returns an Elasticsearch_Extensions\Aggregations\Aggregation object based on the aggregation's query var.

Usage

elasticsearch_extensions()->get_aggregation_by_query_var( string $query_var )

Parameters

$query_var

(string) The machine-readable query var for the aggregation.

Example

$post_type_aggregation = elasticsearch_extensions()->get_aggregation_by_query_var( 'post_type' );

Outputting Aggregation Form Fields

Once you have the aggregation, you can output the form fields using the checkboxes or select methods. When using these methods, you can't control the markup that is generated, although you can use filters to modify things like labels and buckets.

checkboxes

Outputs HTML for a <fieldset> element containing the aggregation's buckets as checkboxes (<input type="checkbox">) and labeled with the aggregation's label in the fieldset's <legend> field.

Usage

$aggregation->checkboxes()

Example

elasticsearch_extensions()->get_aggregation_by_query_var( 'post_type' )->checkboxes();

select

Outputs HTML for a <select> element containing the aggregation's buckets and labeled with the aggregation's label.

Usage

$aggregation->select()

Example

elasticsearch_extensions()->get_aggregation_by_query_var( 'post_type' )->select();

Iterating Over Buckets

If you want to be in full control of the output of an aggregation, including iterating over its buckets, you can use the get_buckets() method in the aggregation object to fetch a list of Bucket objects and loop over them yourself, either to print HTML or populate an API response.

get_buckets

Gets an array of Elasticsearch_Extensions\Aggregations\Bucket objects that contain the count, key, label, and selected properties for each bucket in an aggregation. For example, for a post type aggregation, each bucket is a post type, and the key is the post type name, the label is the post type's human-readable label, the count is the number of documents that match the search criteria and have that post type, and the selected property indicates whether the bucket was requested in the search query (for example, the checkbox was checked).

Usage

$aggregation->get_buckets()

Example

$buckets = elasticsearch_extensions()->get_aggregation_by_query_var( 'post_type' )->get_buckets();

Other Aggregation Properties

You can get other aggregation properties using helper methods on the Aggregation object, such as the label and the query var.

get_label

Gets the human-readable label for the aggregation.

Usage

$aggregation->get_label()

Example

$label = elasticsearch_extensions()->get_aggregation_by_query_var( 'post_type' )->get_label();

get_query_var

Gets the machine-readable query var for the aggregation.

Usage

$aggregation->get_query_var()

Example

$query_var = elasticsearch_extensions()->get_aggregation_by_query_var( 'post_type' )->get_query_var();

get_query_values

Gets an array of selected items for the given aggregation. For example, the checkboxes that are checked, as represented in the URL query string.

Usage

$aggregation->get_query_values()

Example

$values = elasticsearch_extensions()->get_aggregation_by_query_var( 'post_type' )->get_query_values();