Distill

🚧 Work In Progress: Some things may change/break. Feedback welcome.

This Statamic addon allows you to filter, fetch or index the individual values, sets and relations within your entries, from both root and deeply nested fields. It's useful for things like:

• Extracting the text from every Bard field within a replicator
• Finding every asset in the page, or just the first image
• Filtering, sorting and paginating a Grid field or raw array just like a collection
• Adding individual sections of a page to a search index
• Refactoring nested data and sets

Installation

You can search for this addon in the Tools > Addons section of the Statamic control panel and click install, or run the following command from your project root:

composer require jacksleight/statamic-distill

Examples

Find every image in the page

{{ distill:page type="asset:*" is_image:is="true" unique="true" }}
    {{ url }}
{{ /distill:page }}

Extract all Bard text from a page builder

{{ { distill:bard from="builder" } | bard_text }}

Filter, sort and paginate a Grid field

{{ distill:parts_list depth="1" paginate="10" :category:is="get:category" :sort="get:sort" }}
    {{ items }}
        {{ name }} {{ price }}
    {{ /items }}
    {{ paginate }}
        <a href="https://github.com/jacksleight/statamic-distill/blob/main/{{ prev_page }}">←</a>
        <a href="https://github.com/jacksleight/statamic-distill/blob/main/{{ next_page }}">→</a>
    {{ /paginate }}
{{ /distill:parts_list }}

Add sections of a page to a search index

// config/statamic/search.php
'searchables' => [
    'distill:collection:pages:sections',
],
'fields' => ['heading'],

// app/Stills/Sections.php
namespace App\Stills;

use JackSleight\StatamicDistill\Stills\Still;

class Sections extends Still
{
    public function apply($query, $values)
    {
        $query->path('builder.*')->type('set:section');
    }
}

{{# resources/views/search.antlers.html #}}
{{ search:results }}
    {{ if result_type === 'distill:set:section' }}
        <a href="https://github.com/jacksleight/statamic-distill/blob/main/{{ info:source:url }}#{{ id }}">
            {{ title }}
        </a>
    {{ else }}
        ...
    {{ /if }}
{{ /search:results }}

Usage

Distill recursively walks through the value you provide looking for items that match your criteria. It can find individual paragraphs and field values through to entire sets and references to other content.

For optimal performance you should use the from, path, expand, limit and max_depth parameters to restrict where it goes based on what you're looking for. These options don't just filter the final result, they tell Distill where to look and when to stop.

Distill can find references to other entries, terms, assets and users, but it will not walk into those objects. Additionally Distill will only walk raw values if you provide one, it will not walk into a field's raw value.

Distill Tag

The {{ distill:* }} tag accepts the following parameters:

• from (string)
  The name of the source variable (not the variable itself), can be a single field or raw value or an entry, term, asset or user.
• type (string|array)
  The type to match, asterisks can be used as a wildcard and multiple types can be pipe delimited, options are:
  • value:[fieldtype] - A field value
  • set:[handle] - A Replicator or Bard set
  • row:[distill-type] - A Grid row (type can be defined in the field config)
  • node:[type] - A Bard node
  • mark:[type] - A Bard mark
  • entry:[collection] - An entry
  • term:[taxonomy] - A term
  • asset:[container] - An asset
  • user - A user
  • raw:[php-type] - A raw value
• path (string|array)
  The path to match, asterisks can be used as a wildcard and multiple paths can be pipe delimited, paths themselves are dot delimited.
• depth (integer)
  Sets both max_depth and min_depth.
• min_depth (integer)
  The minimim depth to find items from.
• max_depth (integer)
  The maximum depth to find items from.
• unique (boolean, false)
  Filter out duplicate items. Filtering is only applied to these types:
  • entry
  • term
  • asset
  • user
• expand (string|array, all)
  Which types to expand and walk into, asterisks can be used as a wildcard and multiple types can be pipe delimited, options are:
  • set:[handle]
  • row:[distill-type]
  • value:replicator
  • value:bard
  • value:grid
  • value:entries
  • value:terms
  • value:assets
  • value:users
  • raw:array
  • raw:object
• limit (integer)
  The maximum number of items.
• offset (integer)
  The starting item offset.
• paginate (integer)
  Enables pagination and sets the number of items per page.
• sort (string)
  The sort order.
• include_source (boolean, false)
  Whether to include the source value.
• still (string)
  Which still to apply, multiple stills can be pipe delimited.
• [conditions] (mixed)
  Any where conditions.

Each item returned includes an info object that contains the following values:

• type - Type of the item.
• path - Path to the item from the source.

  Sponsoring

  This addon is completely free to use. However fixing bugs, adding features and helping users takes time and effort. If you find this addon useful and would like to support its development any contribution would be greatly appreciated. Thanks! 🙂