eleventy-plugin-filter-page

This Eleventy plugin repository contains two key pieces for "Eleventy Collection Filter" functionality:

• ecf.plugin.js
• ecf.filter.js

Examples

• Campgames Website:
  • live: https://campgamesdb.com/
  • source: gitlab
• Example directory in this repository:
  • live: link
  • source: gitlab

Usage

1. Install the plugin

npm install eleventy-plugin-filter-page

2. Add this plugin to your config

eleventyConfig.addPlugin(ecfPlugin);

3. Configure the filters

There are multiple ways to provide configuration to the plugin, but the configuration itself follows the same schema.

Code for a complete 11ty project with an example config and resulting page can be found in the example folder. You can preview the example website here: link eventually.

Configuration schema

interface PluginConfig {
  collection: string; // Name of the Eleventy collection this config applies to 
  identifyingField?: string; // unique field to each item in the collection. Falls back to 'url' when left empty
  filters: Array< // List of filters available for this collection 
  {
    type: "radio";
    label: string; // Human-readable label shown in the UI 
    field: string; // Front-matter field this filter targets 
  } | {
    type: "checkbox";
    label: string;
    field: string;
  } | {
    type: "text";
    label: string;
    field: string;
    /** Optional external <form> ID for wiring into existing markup. See TODO: Step 5 */
    form?: string;
    options?: {
      placeholder?: string; // Placeholder text shown in the input 
    };
  }
  >;
}

3.1 Config as plugin opts

eleventyConfig.addPlugin(ecfPlugin, {
  config: {
    collection: "posts",
    identifyingField: 'url',
    filters: [ /* ... */ ]
  }
});

3.2 Separate file

In case you want to expose your configuration file to a CMS (ex. DecapCMS), you may want to store the configuration in a separate .json file and import it as follows:

eleventyConfig.addPlugin(ecfPlugin, {
  config: require('./src/_data/ecfConfig.json')
});

A sample of DecapCMS config.yml for this purpose can be seen here: config.yml

3.3 _data/ecfConfig.json

Eleventy exposes files in the _data folder as front-matter metadata to the templates. It is also exposed to this plugin, so you can have a config stored in the ecfConfig metadata collection, or if you prefer to name it something else, you can import it as follows:

eleventyConfig.addPlugin(ecfPlugin, {
  configDataField: 'ecfConfig'
});

or rely on ecfConfig default and import the plugin with no further .eleventy.js configuration:

eleventyConfig.addPlugin(ecfPlugin);

4. Create your search page template

Everyone's styling and HTML layout for their 11ty projects is going to be different. This plugin permits you to adjust the template to your liking, as long as the main building blocks are there.

To get the basic version going, just copy the example template file into your source directory and change targetCollection variable, as well as adjust the resultItem macro to match your collection's fields, and you're good to go. For any further modification, rudimentary knowledge of Nunjucks and Eleventy should suffice.

If you have suggestions on how to go about improving this step (architecture or instructions), please submit a Pull Request or open an Issue in this repository.

DecapCMS

In case you want to expose the configuration file to your CMS, here is the DecapCMS's configuration schema that matches the plugin's config schema.

# DecapCMS configuration excerpt.
collections:
  - label: "Configurations"
    name: "configurations"
    files:
      - label: "Filter Configuration"
        name: "ecfConfig"
        file: "src/_data/ecfConfig.json"
        preview_path: /search
        description: "Filter Configuration"
        extension: json
        format: json
        fields:
          - label: "Configuration Items"
            name: "items"
            widget: list
            summary: "Search Page config for Collection: \"{{ fields.collection }}\""
            allow_add: false
            allow_remove: false
            allow_reorder: false
            fields:
              - label: "Collection ID (string)"
                name: "collection"
                hint: "Codename for the collection that will be filtered"
                widget: string
                required: true
              - label: "Identifying Field"
                name: "identifyingField"
                hint: "A unique field to each item in the collection"
                widget: string
                default: 'url'
              - label: "Filters"
                name: filters
                widget: "list"
                label_singular: "filter"
                summary: "{{fields.label }} - {{fields.type }}"
                fields:
                  - label: "Type"
                    name: "type"
                    hint: "Type of input for the filter"
                    widget: select
                    default: "checkbox"
                    options: ['radio', 'checkbox', 'text']
                  - label: "Label"
                    hint: "Display text for a filter"
                    name: "label"
                    widget: string
                    default: ""
                  - label: "Field"
                    name: "field"
                    hint: "Field that the collection will be filtered by (usually lowercase)"
                    widget: string
                    default: ""
                  - label: "External Form ID"
                    name: "form"
                    widget: string
                    hint: "If you are using a custom <form> template, you need to set this string for it to be found by the script"
                    default: ""
                    required: false
                  - label: "Options"
                    name: "options"
                    widget: object
                    default: {}
                    required: false
                    fields:
                      - label: "Placeholder"
                        name: "placeholder"
                        widget: string
                        hint: "Placeholder for text input"