eleventy-plugin-find

An Eleventy utility filter to find array members that match a set of rules.

Setup

To install this plugin, run the following command at the root of your Eleventy project:

npm install --save eleventy-plugin-find

Next, add the following to the body of the module.exports in your Eleventy config file:

eleventyConfig.addPlugin( require("eleventy-plugin-find") );

Example Scenario

Say you're building a podcast site with Eleventy and the content structure is organized by episode, each consisting of a details page and a transcript page:

+-- src/
  +-- _data/
  +-- _includes/
  +-- content/
    +-- s01/
	  +-- e01/
	    +-- index.md
	    +-- transcript.md
	  +-- e02/
	    +-- index.md
	    +-- transcript.md
    +-- s02/
+-- .eleventy.js

The frontmatter for an episode's details page might look like this:

---
season: 1
episode: 1
title: Unbridled Moose Game
keywords: [unbridled moose game, games, moose]
enclosure:
  duration: "45:13"
  filename: unbridled-moose-game.mp3
  length: 66561568

tags: [episodes]
---

For simplicity of content management by a variety of contributors, it's important that all metadata about an episode exist in the index.md frontmatter, rather than using a JSON- or JavaScript-based directory data file to define shared data.

However, the episode details page and the transcript page both need to display the episode's title and episode number. How can we accomplish without duplicating data between files?

Using an array of property-value rules to search by season and episode values, our transcript layout can use the find filter to extract the correct Eleventy template object from our episodes collection:

# transcript.njk
---
layout: layouts/base.njk
---
{%- set episodeTemplate = collections.episodes | find([
	{ property: "data.season", value: season },
	{ property: "data.episode", value: episode }
]) -%}

By setting the filter result to a template variable, as in episodeTemplate in the Nunjucks example above, we can then refer to any property of the Eleventy template object throughout the page.

For example, to display the episode and title values defined in src/content/s01/e01/index.md on the transcript page for the same episode, the transcript.njk template might look something like this:

<h1>Episode {{ episodeTemplate.data.episode }}: {{ episodeTemplate.data.title }}</h1>

which would be rendered as:

<h1>Episode 1: Unbridled Moose Game</h1>

If the title changes to something, say, a little more fowl, changing that value in index.md will automatically update the title displayed on the corresponding transcript page. Honk! 🎉

Usage

{{ <array> | find( <ruleset> ) }}

While filtering collection objects using a property-value format is probably the find filter's most common use, it supports a variety of ruleset formats.

Single primitive

---
fruits:
  - apple
  - banana
  - cherry
---
{{ fruits | find( "cherry" ) }}

This will return "cherry"

Array of primitives

---
fruits:
  - apple
  - banana
  - cherry
---
{{ fruits | find( ["banana", "cherry"] ) }}

This will return "banana", the first matching primitive

Single property-value object

---
fruits:
  - name: apple
    color: red
    sour: false

  - name: banana
    color: yellow
    sour: false

  - name: lemon
    color: yellow
    sour: true
---
{{ fruits | find(
	{ property: "name", value: "banana" }
)}}

This will return the first array item whose property name has the value "banana", { name: "banana", [...] }

🤹 find supports dot notation for specifying nested property names (ex., property: "data.title")

Array of property-value objects

---
fruits:
  - name: apple
    color: red
	sour: false

  - name: banana
    color: yellow
	sour: false

  - name: lemon
    color: yellow
	sour: true
---
{{ fruits | find([
	{ property: "color", value: "yellow" },
	{ property: "sour", value: true }
]) }}

This will return the first array item whose property color has the value "yellow" and whose property sour has the value true, { name: "lemon", [...] }

🤹 find supports dot notation for specifying nested property names (ex., property: "data.title")