Plate logoMultisite
Changelog
Tags

search_results

Last updated: · Published:

A block where the search results of the passed search query are available. Expects one argument, which is the search query.

The following variables are available within the block:

  • search_results: An array of Posts that match the search query.

Use request.query_object to use a search term passed as a URL parameter.

The block accepts the following extra optional parameters:

  • size, e.g. size: 50. The maximum search results, so the request load time can be limited, even when there is a very large amount of search results. Default: 100.
  • page, per_page, e.g. page: 2, per_page: 50: Pagination for search results. Default: page: 1, per_page: 100
  • window_size, e.g. window_size: 5: Number of pages to show around the current page in pagination navigation. Default: 3
  • pagination_name, e.g. pagination_name: "turn": Name of the URL parameter used for pagination. Default: "page". If set to "turn", pagination URLs will be generated as ?turn=2
  • filters: refine search results by specifying conditions that must be met by the returned data. This parameter allows structured filtering based on field values, operators, and conditions.
  • sort_by: Sorts the search results. Supports sorting by multiple fields. The order of fields in the sort_by determines the priority of sorting.

Search results attributes:

  • search_results_total_results: Total number of results
  • search_results_page_count: Number of pages
  • search_results_per_page: Number of item per page
  • search_paginate: Pagination object with navigation and metadata
{% search_results "search query", per_page: 10, page: 2 %}
  <!-- Access pagination info -->
  Current page: {{ search_paginate.current_page }}
  Total pages: {{ search_paginate.page_count }}
  Total results: {{ search_paginate.total_results }}
  
  <!-- Loop through current page results -->
  {% for post in search_paginate.items %}
    <h3>{{ post.title }}</h3>
  {% endfor %}
  
  <!-- Navigation -->
  {% if search_paginate.previous %}
    <a href="{{ search_paginate.previous.url }}">Previous</a>
  {% endif %}
  
  {% for page in search_paginate.pages %}
    {% if page.is_link %}
      <a href="{{ page.url }}">{{ page.index }}</a>
    {% else %}
      <span>{{ page.index }}</span>
    {% endif %}
  {% endfor %}
  
  {% if search_paginate.next %}
    <a href="{{ search_paginate.next.url }}">Next</a>
  {% endif %}
{% endsearch_results %}

Pagination Methods

The search_results tag supports two ways to handle pagination:

1. URL-based Pagination (Automatic)

By default, pagination is automatically handled through URL parameters. The tag reads the current page from the URL parameter page (e.g., ?page=2).

{% search_results "search query", per_page: 10 %}
  <!-- Automatically reads ?page=2 from URL -->
  Current page: {{ search_paginate.current_page }}
{% endsearch_results %}

You can override the default URL parameter by using the pagination_name parameter.

{% search_results "search query", per_page: 10, pagination_name: "turn" %}
  <!-- Now reads ?turn=2 from URL instead of ?page=2 -->
  Current page: {{ search_paginate.current_page }}
{% endsearch_results %}

2. Manual Page Override

You can also manually specify the current page using the page parameter, which overrides URL-based pagination:

{% search_results "search query", per_page: 10, page: 3 %}
  <!-- Always shows page 3, regardless of URL parameter -->
  Current page: {{ search_paginate.current_page }}
{% endsearch_results %}

Pagination Object

search_paginate
{
  "current_page" => current_page,        # Current page number
  "items" => search_results,             # Array of search results for current page
  "page_count" => page_count,           # Total number of pages
  "total_results" => total_results,     # Total number of search results
  "per_page" => per_page,               # Number of items per page
  "pages" => [],                        # Array of page object for navigation
  "previous" => previous_link,          # Previous page object (if available)
  "next" => next_link                   # Next page object (if available)
}
page_object
{
  "index" => page_number,               # Page number or "&hellip;" for ellipsis
  "url" => page_url,                    # URL for the page (if it's a link)
  "is_link" => true/false               # Whether this page is clickable
}

Search weights

Default weight value:

  • post title: 4
  • post slug: 3
  • post SEO Title/Description: 2
  • post body content: 1

The importance of a content field ranges from 1 to 5. Set it to 5 if you consider this field the most important.

Customize search weights

You can specify the following weight parameters:

  • title_weight
  • slug_weight
  • seo_title_weight
  • seo_description_weight
  • post_body_content_weight

Excluding Search Body Content

If you do not want to include post_body_content in the search, set exclude_body_content to true.

Ngram Search

Ngram (partial word) search will be enabled for title, SEO fields, slug, and body content if the search keyword is 10 characters or fewer. The importance of ngrams for these fields will be 0.6 times the importance of the respective field.

{% search_results "test", title_weight: 2, exclude_body_content: true %}
 ....
{% endsearch_results %}

Filters

{%- capture plateFilters -%}
  [
    { 
      "field": "post.title",
      "operator": "=",
      "value": "Test"
    },
    {
      "field": "post.slug",
      "operator": "in",
      "value": ["test", "dev-test"]
    }
  ]
{%- endcapture -%}
{% search_results "cms", filters: plateFilters %}
 ....
{% endsearch_results %}

Filters Parameter:

The filters parameter accepts an array of filter objects, where each object contains the following attributes:

  • field (string): Specifies the data field to be filtered. It should be a valid field path within the data structure.
  • operator (string): Defines the comparison operation to apply. Supported operators include:
    • =: Equals
    • !=: Not equal
    • >: Greater than
    • <: Less than
    • >=: Greater than or equal to
    • <=: Less than or equal to
    • in: Matches any value within a given list
    • not_in: Excludes values within a given list
    • exists: Checks if a field exists
    • not_exists: Checks if a field does not exist
    • contains: Checks if a field contains a specified substring
    • not_contains: Checks if a field does not contain a specified substring
  • value (varied type): Specifies the value to compare against the field. The data type should match the field's expected type (e.g., string, number, boolean, or array for in/not_in).

Operators example

{ "field": "post.author.name", "operator": "=", "value": "David" }
{ "field": "post.author.name", "operator": "!=", "value": "David" }
{ "field": "post.year", "operator": ">", "value": 1990 }
{ "field": "post.year", "operator": "<", "value": 2000 }
{ "field": "post.year", "operator": ">=", "value": 1990 }
{ "field": "post.year", "operator": "<=", "value": 2000 }
{ "field": "post.agenda.start_date", "operator": "<=", "value": "2025-01-03T14:07:00Z" } // ISO 8601 timestamp
{ "field": "post.tags", "operator": "in", "value": ["tag1", "tag2"] }
{ "field": "post.tags", "operator": "not_in", "value": ["tag1"] }
{ "field": "post.author.name", "operator": "exists", "value": true }
{ "field": "post.author.name", "operator": "not_exists", "value": true }
{ "field": "post.author.name", "operator": "contains", "value": "delta" }
{ "field": "post.author.name", "operator": "not_contains", "value": "delta" }

Usage Considerations

  • Ensure that field names match the structure of the dataset.
  • Use appropriate data types for value to prevent mismatches.
  • Combining multiple filters will result in an AND operation; ensure filters are structured correctly for the desired logic.
  • Use debug search in the dashboard to analyze query, troubleshoot filter conditions, and ensure expected results are returned.

Sort options

  • Format: field-[sort-direction]-[sort-type]
  • Sort directions: ascending, descending
  • Sort types: string, float, long, date
{% search_results "", sort_by: "post.title" %}

{% search_results "", sort_by: "post.product.price-descending-float, post.id-long" %}

Sorting Support

Supports multiple sorting options (the order of fields in the sort_by determines the priority of sorting). If the sort type is different from the default (string), the user must explicitly specify it. By default, sorting is done in ascending order using the string type.

  • post.title → Sort by title as string, ascending (default).
  • post.id-long → Sort by id as long, ascending.
  • post.product.price-descending-float → Sort by price as float, descending.
  • post.product.price-ascending-float → Sort by price as float, ascending.

paginate

search_form

Copyright © 2025