eleventy-plugin-filter-page 0.1.0

package/LICENSE

@@ -0,0 +1,7 @@
+Copyright (c) 2026 Daniel Maiovskyi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,161 @@
+# eleventy-plugin-filter-page
+This Eleventy plugin repository contains two key pieces for "Eleventy Collection Filter" functionality:
+- ecf.plugin.js
+- ecf.filter.js
+
+## Usage
+### 1. Install the plugin
+```sh
+npm install eleventy-plugin-filter-page
+```
+
+### 2. Add this plugin to your config
+```js
+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](./example/). You can preview the example website here: link eventually.
+
+#### Configuration schema
+```ts
+interface PluginConfig {
+	collection: string; // Name of the Eleventy collection this config applies to 
+	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
+```js
+	eleventyConfig.addPlugin(ecfPlugin, {
+		config: {
+            collection: "posts",
+            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:
+```js
+	eleventyConfig.addPlugin(ecfPlugin, {
+		config: require('./src/_data/ecfConfig.json')
+	});
+```
+
+A sample of DecapCMS `config.yml` for this purpose can be seen here: [config.yml](./example/src/admin/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:
+```js
+	eleventyConfig.addPlugin(ecfPlugin, {
+		configDataField: 'ecfConfig'
+	});
+```
+
+or rely on ecfConfig default and import it without settings:
+```js
+	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](./example/src/filter.njk) into your source directory and change the variables `targetCollection` and `identifyingField`, 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](#configuration-schema).
+
+```yml
+# 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: "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"
+```
+
+## TODO
+- NPM publish .gitlab-ci script
+- example website .gitlab-ci script
+- more filter types (number range)

package/dist/ecf.filter.js

@@ -0,0 +1,197 @@
+/* The following constants must be defined before this script loads: */
+/* global ecfData:readonly -- the data to filter */
+/* global filterConfig:readonly -- configuration for the filter */
+
+/**
+ * @typedef {Object<string, string | string[]>} StringMap
+ * @typedef {StringMap & { _id: string }} Entry
+ */
+
+/**
+ * Defined in the template file as JSON input for the script.
+ * @type {Entry[]} */
+globalThis.ecfData;
+
+/**
+ * Defined in the template file. Direct forward of the filter's JSON config file into a JS Object variable.
+ * @type {Object[]} */
+globalThis.filterConfig;
+
+
+if (typeof ecfData === "undefined") {
+	alert('"ecfData" variable must be defined');
+	throw new Error("Global `ecfData` must be defined before this script runs.");
+}
+
+if (typeof filterConfig === "undefined") {
+	alert('"filterConfig" variable must be defined');
+	throw new Error("Global `filterConfig` must be defined before this script runs.");
+}
+
+/* BEGIN Helper Functions */
+/**
+ * Merges `source` into `target`.
+ * @param {FormData} target
+ * @param {FormData} source
+ * @returns {FormData} `target` reference */
+function mergeFormData(target, source) {
+	for (const [key, value] of source.entries()) {
+		target.append(key, value);
+	}
+	return target;
+}
+/** @returns {Element|Element[]} element */
+function $(query) {
+	let q;
+	return (q = document.querySelectorAll(query)).length == 1 ? q[0] : q;
+}
+/* END Helper Functions */
+
+/* BEGIN Script */
+const defaultFormId = "ecf-filters";
+
+const ecfForms = filterConfig
+	.filter(filter => filter.form)
+	.map(f => f.form)
+	.concat([defaultFormId])
+	.map(idString => {
+		return document.getElementById(idString);
+	});
+
+// Minor template Validation
+const formTemplateValidation = ecfForms.every(el => {
+	return (el != null && el != undefined && el.tagName.toLowerCase() === 'form');
+});
+if (!formTemplateValidation) {
+	alert("Improperly configured template. All <form> elements with IDs from the filter configuration file must exist in the layout.");
+}
+
+// mapping each _id to an Element
+const idToElementMap = new Map();
+$("[data-search-id]").forEach(el => {
+	idToElementMap.set(el.getAttribute("data-search-id"), el);
+});
+
+
+/**
+ * Maps field name to current filter value from all forms
+ * @returns {Promise<Readonly<StringMap>>}
+ * */
+async function preProcessFilters() {
+	// merge all form data into one
+	const formData = ecfForms.reduce((prev, curr) => {
+		return mergeFormData(prev, new FormData(curr));
+	}, new FormData());
+	const filterValues = {};
+	for (const [key, value] of formData.entries()) {
+		// checkbox
+		if (key.slice(0, 5) == "ecf-c") {
+			let l = key.split(" ");
+			if (!filterValues[l[1]]) {
+				filterValues[l[1]] = [];
+			}
+			if (value == "on") {
+				filterValues[l[1]].push(l[2]);
+			}
+		}
+		// text input
+		else if (key.slice(0, 5) == "ecf-t") {
+			let l = key.split(" ");
+			if (value.length > 0) {
+				filterValues[l[1]] = value;
+			}
+		}
+		// radio
+		else {
+			filterValues[key] = value;
+		}
+	}
+	return filterValues;
+}
+
+/**
+ * Applies `filterValues` to a global `ecfData` array.
+ * @param {Promise<StringMap>} filterValues
+ * @returns {Promise<Entry[]>} - filtered subset of the `ecfData` array.
+ * */
+async function applyFilterValues(filterValues) {
+	return ecfData.filter(function(entry) {
+		return filterConfig.map((filter) => {
+			const filterValue = filterValues[filter.field] || false;
+			if (!filterValue) return true;
+			switch (filter.type) {
+				case 'radio': {
+					return entry[filter.field] === filterValue;
+				}
+				case 'checkbox': {
+					return filterValue.every(attr => entry[filter.field].includes(attr));
+				}
+				case 'text': {
+					return entry[filter.field].toLowerCase().indexOf(filterValue) !== -1;
+				}
+				default: {
+					return false;
+				}
+			}
+		}).every(el => (el));
+	});
+}
+
+/**
+ * Hides all the elements of entries that are NOT in the `filteredData` array
+ * - uses global `idToElementMap`
+ * @param {Entry[]} filteredData - array of filtered ecfData entries
+ * */
+async function hideFilteredData(filteredData) {
+	// hide all elements
+	idToElementMap.values().forEach(element => element.style.display = "none");
+	// then unhide elements that were filtered out
+	filteredData.forEach(entry => {
+		idToElementMap.get(entry._id).style.display = '';
+	});
+}
+
+/** Run on each filter update */
+function handleFilterInput() {
+	preProcessFilters().then(applyFilterValues).then(hideFilteredData);
+}
+
+globalThis.selectAllFilterGroup = function selectAllFilterGroup(fieldName) {
+	const filter = filterConfig.find(filter => filter.field == fieldName);
+	if (filter.type != 'checkbox') {
+		alert("Misconfiguration of Filters. Select All button must only be present on checkbox filters.")
+	}
+	ecfForms.forEach(form => {
+		form
+			.querySelectorAll('input[type="checkbox"][name^="ecf-c ' + fieldName + '"]')
+			.forEach(checkbox => {
+				checkbox.checked = true;
+			});
+	})
+	handleFilterInput();
+}
+
+globalThis.clearFilterGroup = function clearFilterGroup(fieldName) {
+	const filter = filterConfig.find(filter => filter.field == fieldName);
+	if (filter.type == 'radio') {
+		ecfForms.forEach(form => {
+			form
+				.querySelectorAll('input[type="radio"][name="' + fieldName + '"]')
+				.forEach(radio => { radio.checked = false; });
+		})
+	}
+	if (filter.type == 'checkbox') {
+		ecfForms.forEach(form => {
+			form
+				.querySelectorAll('input[type="checkbox"][name^="ecf-c ' + fieldName + '"]')
+				.forEach(checkbox => { checkbox.checked = false; });
+		})
+	}
+	handleFilterInput();
+}
+
+ecfForms.forEach(form => {
+	form.addEventListener("input", handleFilterInput);
+	form.addEventListener("onchange", handleFilterInput);
+	form.addEventListener("submit", e => { e.preventDefault() });
+})

package/dist/ecf.filter.min.js

@@ -0,0 +1 @@
+if(typeof ecfData==='undefined'){alert('"ecfData" variable must be defined');throw Error('Global `ecfData` must be defined before this script runs.')}if(typeof filterConfig==='undefined'){alert('"filterConfig" variable must be defined');throw Error('Global `filterConfig` must be defined before this script runs.')}function a(b,B){for(const[C,_b] of B.entries())b.append(C,_b);return b}function $(_a){let q;return (q=document.querySelectorAll(_a)).length==1?q[0]:q}var c='ecf-filters',d=filterConfig.filter(D=>D.form).map(f=>f.form).concat([c]).map(_A=>document.getElementById(_A)),A=d.every(E=>(E!=null&&E!=void 0&&E.tagName.toLowerCase()==='form'));!A&&alert('Improperly configured template. All <form> elements with IDs from the filter configuration file must exist in the layout.');var _=new Map;for(const aA of $('[data-search-id]'))_.set(aA.getAttribute('data-search-id'),aA);function g(){var aB=d.reduce((aC,aD)=>a(aC,new FormData(aD)),new FormData),_B={};for(const[aE,aF] of aB.entries())if(aE.slice(0,5)=='ecf-c'){let l=aE.split(' ');!_B[l[1]]&&(_B[l[1]]=[]);aF=='on'&&_B[l[1]].push(l[2])}else if(aE.slice(0,5)=='ecf-t'){let l=aE.split(' ');aF.length>0&&(_B[l[1]]=aF)}else _B[aE]=aF;return _B}function h(aG){return ecfData.filter(aH=>filterConfig.map(aI=>{var aJ=aG[aI.field]||!1;if(!aJ)return!0;switch(aI.type) {case 'radio':return aH[aI.field]===aJ;case 'checkbox':return aJ.every(aK=>aH[aI.field].includes(aK));case 'text':return aH[aI.field].toLowerCase().indexOf(aJ)!==-1;default:return!1}}).every(el=>(el)))}function i(aL){for(const aM of _.values())aM.style.display='none';for(const aN of aL)_.get(aN._id).style.display=''}function j(){g().then(h).then(i)}globalThis.selectAllFilterGroup=function aP(aO){var _c=filterConfig.find(aQ=>aQ.field==aO);_c.type!='checkbox'&&alert('Misconfiguration of Filters. Select All button must only be present on checkbox filters.');for(const aR of d)for(const aS of aR.querySelectorAll(`input[type="checkbox"][name^="ecf-c ${aO}"]`))aS.checked=!0;j()};globalThis.clearFilterGroup=function aU(aT){var _C=filterConfig.find(aV=>aV.field==aT);_C.type=='radio';_C.type=='checkbox';j()};for(const aW of d){aW.addEventListener('input',j);aW.addEventListener('onchange',j);aW.addEventListener('submit',e=>e.preventDefault())}

package/dist/ecf.plugin.js

@@ -0,0 +1,92 @@
+/**
+ * @typedef {{type: string, label: string, field: string}} FilterGroupConfig
+ * @typedef {{collection: string, filters: Array<FilterGroupConfig> }} FilterCollectionConfig
+ * @typedef {{items: Array<FilterCollectionConfig>}} EcfConfig
+ * @typedef {{configDataField: string} | {config: EcfConfig}} PluginConfig
+ */
+
+const defaultConfigFieldName = "ecfConfig";
+
+/**
+ * @param {Object} [eleventyConfig] - exposed to a plugin by Eleventy by default
+ * @param {PluginConfig} [pluginConfig=null] - configuration of the plugin
+ */
+function ecfPlugin(eleventyConfig, pluginConfig = null) {
+	// config validation
+	let configFromMetadata = false;
+	let importedConfig = {};
+	if (pluginConfig != null) {
+		if (pluginConfig.configDataField) {
+			configFromMetadata = true;
+		}
+		else if (pluginConfig.config && typeof pluginConfig.config === 'object') {
+			importedConfig = pluginConfig.config;
+		}
+		else {
+			throw new Error("Invalid ECF configuration, missing 'config' or 'configDataField' or 'configFile' property")
+		}
+	} else {
+		// will use "ecfConfig" collection by default
+		configFromMetadata = true;
+	}
+
+	/* Processes all entries in all configured collections for unique field values,
+	 * then duplicates the config into the 'ecfFilters' collection with the 'values' field added. */
+	eleventyConfig.addCollection("ecfFilters", function(api) {
+		if (configFromMetadata) {
+			const configFieldName = pluginConfig.configDataField || defaultConfigFieldName;
+			const collection = api.getAll()[0].data[configFieldName];
+			if (collection === undefined || collection === null) {
+				throw new Error(`ECF configuration collection "${configFieldName}" not detected`)
+			}
+			importedConfig = collection;
+		}
+		if (!importedConfig || Object.keys(importedConfig).length == 0) {
+			throw new Error("Invalid ECF configuration")
+		}
+
+		if (Object.prototype.hasOwnProperty.call(importedConfig, "items"))
+			importedConfig = importedConfig.items;
+
+		const ecfFiltersCollection = {};
+		importedConfig.forEach(function(collectionConfig) {
+			let { collection, filters } = collectionConfig;
+			// making sure we're not making config collection edits in-place.
+			let filterConfig = configFromMetadata ? JSON.parse(JSON.stringify(filters)) : filters;
+
+			// convert to Set to accept only unique values
+			for (const filter of filterConfig) {
+				filter.values = new Set();
+			}
+			const entries = api.getFilteredByTag(collection);
+			entries.forEach(entry => {
+				for (const filter of filterConfig) {
+					switch (filter.type) {
+						case "radio": {
+							let value = entry.data[filter.field];
+							let strValue = typeof value !== 'string' ? value.toString() : value;
+							filter.values.add(strValue);
+							break;
+						}
+						case "checkbox": {
+							entry.data[filter.field]?.forEach(value => {
+								let strValue = typeof value !== 'string' ? value.toString() : value;
+								filter.values?.add(strValue)
+							});
+							break;
+						}
+					}
+				}
+			});
+
+			// converting from a Set into Array so templates can read it
+			for (const filter of filterConfig) {
+				filter.values = [...filter.values].filter(val => val != undefined && val != null);
+			}
+			ecfFiltersCollection[collection] = filterConfig;
+		});
+		return ecfFiltersCollection;
+	});
+}
+
+module.exports = ecfPlugin;

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "eleventy-plugin-filter-page",
+  "version": "0.1.0",
+  "description": "11ty plugin to create collection filter pages",
+  "main": "dist/ecf.plugin.js",
+  "files": [
+    "dist/",
+    "README.md",
+    "LICENSE"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://gitlab.com/excitedfellas/eleventy-plugin-filter-page.git"
+  },
+  "bugs": {
+    "url": "https://gitlab.com/excitedfellas/eleventy-plugin-filter-page/-/issues"
+  },
+  "scripts": {
+    "lint": "eslint",
+    "build": "rm -rf dist && mkdir -p dist && cp -R src/. dist/ && minify dist/ecf.filter.js > dist/ecf.filter.min.js",
+    "prepublishOnly": "npm run build"
+  },
+  "homepage": "https://gitlab.com/excitedfellas/eleventy-plugin-filter-page",
+  "keywords": [
+    "11ty",
+    "eleventy",
+    "javascript",
+    "plugin"
+  ],
+  "author": "Daniel Mayovskiy",
+  "license": "MIT",
+  "devDependencies": {
+    "@eslint/js": "^9.39.2",
+    "eslint": "^9.39.2",
+    "globals": "^17.0.0",
+    "minify": "^11.0.0"
+  }
+}