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"
)