eleventy-plugin-filter-page 0.1.1 → 0.2.0

package/README.md

@@ -3,6 +3,15 @@ This Eleventy plugin repository contains two key pieces for "Eleventy Collection
 - ecf.plugin.js
 - ecf.filter.js
 
+## Examples
+
+- Campgames Website:
+  - live: [https://campgamesdb.com/](https://campgamesdb.com/)
+  - source: [gitlab](https://gitlab.com/excitedfellas/campgames-db) 
+- Example directory in this repository:
+  - live: [link](https://eleventy-plugin-filter-page-01919e.gitlab.io/filter/)
+  - source: [gitlab](https://gitlab.com/excitedfellas/eleventy-plugin-filter-page/-/tree/main/example)
+
 ## Usage
 ### 1. Install the plugin
 ```sh
@@ -19,69 +28,73 @@ There are multiple ways to provide configuration to the plugin, but the configur
 
 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
+##### 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 
-		};
-	}
-	>;
+  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
 ```js
-	eleventyConfig.addPlugin(ecfPlugin, {
-		config: {
-            collection: "posts",
-            filters: [ /* ... */ ]
-        }
-	});
+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:
 ```js
-	eleventyConfig.addPlugin(ecfPlugin, {
-		config: require('./src/_data/ecfConfig.json')
-	});
+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'
-	});
+eleventyConfig.addPlugin(ecfPlugin, {
+  configDataField: 'ecfConfig'
+});
 ```
 
-or rely on ecfConfig default and import it without settings:
+or rely on `ecfConfig` default and import the plugin with no further `.eleventy.js` configuration:
+
 ```js
-	eleventyConfig.addPlugin(ecfPlugin);
+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.
+To get the basic version going, just copy the [example template file](./example/src/filter.njk) 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.
 
@@ -115,6 +128,11 @@ collections:
                 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"

package/dist/ecf.filter.js

@@ -4,7 +4,7 @@
 
 /**
  * @typedef {Object<string, string | string[]>} StringMap
- * @typedef {StringMap & { _id: string }} Entry
+ * @typedef {StringMap & { ecf_id: string }} Entry
  */
 
 /**
@@ -66,10 +66,10 @@ 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
+// mapping each ecf_id to an Element
 const idToElementMap = new Map();
-$("[data-search-id]").forEach(el => {
-	idToElementMap.set(el.getAttribute("data-search-id"), el);
+$("[data-ecf-id]").forEach(el => {
+	idToElementMap.set(el.getAttribute("data-ecf-id"), el);
 });
 
 
@@ -147,7 +147,7 @@ async function hideFilteredData(filteredData) {
 	idToElementMap.values().forEach(element => element.style.display = "none");
 	// then unhide elements that were filtered out
 	filteredData.forEach(entry => {
-		idToElementMap.get(entry._id).style.display = '';
+		idToElementMap.get(entry.ecf_id).style.display = '';
 	});
 }
 

package/dist/ecf.filter.min.js

@@ -1 +1 @@
-if(globalThis.ecfData,"undefined"==typeof ecfData)throw alert('"ecfData" variable must be defined'),new Error("Global `ecfData` must be defined before this script runs.");if("undefined"==typeof filterConfig)throw alert('"filterConfig" variable must be defined'),new Error("Global `filterConfig` must be defined before this script runs.");function mergeFormData(e,t){for(var[r,n]of t.entries())e.append(r,n);return e}function $(e){return 1==(e=document.querySelectorAll(e)).length?e[0]:e}let defaultFormId="ecf-filters",ecfForms=filterConfig.filter(e=>e.form).map(e=>e.form).concat([defaultFormId]).map(e=>document.getElementById(e)),formTemplateValidation=ecfForms.every(e=>null!=e&&"form"===e.tagName.toLowerCase()),idToElementMap=(formTemplateValidation||alert("Improperly configured template. All <form> elements with IDs from the filter configuration file must exist in the layout."),new Map);async function preProcessFilters(){var e,t,r,n={};for([e,t]of ecfForms.reduce((e,t)=>mergeFormData(e,new FormData(t)),new FormData).entries())"ecf-c"==e.slice(0,5)?(n[(r=e.split(" "))[1]]||(n[r[1]]=[]),"on"==t&&n[r[1]].push(r[2])):"ecf-t"==e.slice(0,5)?(r=e.split(" "),0<t.length&&(n[r[1]]=t)):n[e]=t;return n}async function applyFilterValues(n){return ecfData.filter(function(r){return filterConfig.map(t=>{var e=n[t.field]||!1;if(!e)return!0;switch(t.type){case"radio":return r[t.field]===e;case"checkbox":return e.every(e=>r[t.field].includes(e));case"text":return-1!==r[t.field].toLowerCase().indexOf(e);default:return!1}}).every(e=>e)})}async function hideFilteredData(e){idToElementMap.values().forEach(e=>e.style.display="none"),e.forEach(e=>{idToElementMap.get(e._id).style.display=""})}function handleFilterInput(){preProcessFilters().then(applyFilterValues).then(hideFilteredData)}$("[data-search-id]").forEach(e=>{idToElementMap.set(e.getAttribute("data-search-id"),e)}),globalThis.selectAllFilterGroup=function(t){"checkbox"!=filterConfig.find(e=>e.field==t).type&&alert("Misconfiguration of Filters. Select All button must only be present on checkbox filters."),ecfForms.forEach(e=>{e.querySelectorAll('input[type="checkbox"][name^="ecf-c '+t+'"]').forEach(e=>{e.checked=!0})}),handleFilterInput()},globalThis.clearFilterGroup=function(t){var e=filterConfig.find(e=>e.field==t);"radio"==e.type&&ecfForms.forEach(e=>{e.querySelectorAll('input[type="radio"][name="'+t+'"]').forEach(e=>{e.checked=!1})}),"checkbox"==e.type&&ecfForms.forEach(e=>{e.querySelectorAll('input[type="checkbox"][name^="ecf-c '+t+'"]').forEach(e=>{e.checked=!1})}),handleFilterInput()},ecfForms.forEach(e=>{e.addEventListener("input",handleFilterInput),e.addEventListener("onchange",handleFilterInput),e.addEventListener("submit",e=>{e.preventDefault()})});
+if(globalThis.ecfData,"undefined"==typeof ecfData)throw alert('"ecfData" variable must be defined'),new Error("Global `ecfData` must be defined before this script runs.");if("undefined"==typeof filterConfig)throw alert('"filterConfig" variable must be defined'),new Error("Global `filterConfig` must be defined before this script runs.");function mergeFormData(e,t){for(var[r,n]of t.entries())e.append(r,n);return e}function $(e){return 1==(e=document.querySelectorAll(e)).length?e[0]:e}let defaultFormId="ecf-filters",ecfForms=filterConfig.filter(e=>e.form).map(e=>e.form).concat([defaultFormId]).map(e=>document.getElementById(e)),formTemplateValidation=ecfForms.every(e=>null!=e&&"form"===e.tagName.toLowerCase()),idToElementMap=(formTemplateValidation||alert("Improperly configured template. All <form> elements with IDs from the filter configuration file must exist in the layout."),new Map);async function preProcessFilters(){var e,t,r,n={};for([e,t]of ecfForms.reduce((e,t)=>mergeFormData(e,new FormData(t)),new FormData).entries())"ecf-c"==e.slice(0,5)?(n[(r=e.split(" "))[1]]||(n[r[1]]=[]),"on"==t&&n[r[1]].push(r[2])):"ecf-t"==e.slice(0,5)?(r=e.split(" "),0<t.length&&(n[r[1]]=t)):n[e]=t;return n}async function applyFilterValues(n){return ecfData.filter(function(r){return filterConfig.map(t=>{var e=n[t.field]||!1;if(!e)return!0;switch(t.type){case"radio":return r[t.field]===e;case"checkbox":return e.every(e=>r[t.field].includes(e));case"text":return-1!==r[t.field].toLowerCase().indexOf(e);default:return!1}}).every(e=>e)})}async function hideFilteredData(e){idToElementMap.values().forEach(e=>e.style.display="none"),e.forEach(e=>{idToElementMap.get(e.ecf_id).style.display=""})}function handleFilterInput(){preProcessFilters().then(applyFilterValues).then(hideFilteredData)}$("[data-ecf-id]").forEach(e=>{idToElementMap.set(e.getAttribute("data-ecf-id"),e)}),globalThis.selectAllFilterGroup=function(t){"checkbox"!=filterConfig.find(e=>e.field==t).type&&alert("Misconfiguration of Filters. Select All button must only be present on checkbox filters."),ecfForms.forEach(e=>{e.querySelectorAll('input[type="checkbox"][name^="ecf-c '+t+'"]').forEach(e=>{e.checked=!0})}),handleFilterInput()},globalThis.clearFilterGroup=function(t){var e=filterConfig.find(e=>e.field==t);"radio"==e.type&&ecfForms.forEach(e=>{e.querySelectorAll('input[type="radio"][name="'+t+'"]').forEach(e=>{e.checked=!1})}),"checkbox"==e.type&&ecfForms.forEach(e=>{e.querySelectorAll('input[type="checkbox"][name^="ecf-c '+t+'"]').forEach(e=>{e.checked=!1})}),handleFilterInput()},ecfForms.forEach(e=>{e.addEventListener("input",handleFilterInput),e.addEventListener("onchange",handleFilterInput),e.addEventListener("submit",e=>{e.preventDefault()})});

package/dist/ecf.plugin.js

@@ -1,11 +1,33 @@
 /**
  * @typedef {{type: string, label: string, field: string}} FilterGroupConfig
- * @typedef {{collection: string, filters: Array<FilterGroupConfig> }} FilterCollectionConfig
+ * @typedef {{collection: string, filters: Array<FilterGroupConfig>, identifyingField?: string }} FilterCollectionConfig
  * @typedef {{items: Array<FilterCollectionConfig>}} EcfConfig
  * @typedef {{configDataField: string} | {config: EcfConfig}} PluginConfig
  */
 
 const defaultConfigFieldName = "ecfConfig";
+const defaultIdentifyingField = "url";
+
+function ecfResolveId(item, key) {
+	if (!item || !key) return undefined;
+
+	// Template-backed items (normal Eleventy collection entries)
+	if (item.data && key in item.data) {
+		return item.data[key];
+	}
+
+	// Direct property on the item (raw JSON collections)
+	if (key in item) {
+		return item[key];
+	}
+
+	// Common Eleventy fallbacks
+	if (key === "url" && item.url) return item.url;
+	if (key === "fileSlug" && item.fileSlug) return item.fileSlug;
+	if (key === "inputPath" && item.inputPath) return item.inputPath;
+
+	return undefined;
+}
 
 /**
  * @param {Object} [eleventyConfig] - exposed to a plugin by Eleventy by default
@@ -14,43 +36,60 @@ const defaultConfigFieldName = "ecfConfig";
 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;
-	}
+	let finalPluginConfig = {};
+	let finalPluginConfigComputed = false;
 
-	/* 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`)
+	/** @returns {Array<FilterCollectionConfig>} */
+	function getFinalConfig(eleventyCollectionApi) {
+		if (finalPluginConfigComputed) {
+			return finalPluginConfig;
+		} else {
+			// first checking where to get config from
+			if (pluginConfig != null) {
+				if (pluginConfig.configDataField) {
+					configFromMetadata = true;
+				}
+				else if (pluginConfig.config && typeof pluginConfig.config === 'object') {
+					finalPluginConfig = pluginConfig.config;
+				}
+				else {
+					throw new Error("Invalid ECF configuration, missing 'config' or 'configDataField'")
+				}
+			} else {
+				// fallback to collectionEntry.data["ecfConfig"] as config source
+				configFromMetadata = true;
 			}
-			importedConfig = collection;
-		}
-		if (!importedConfig || Object.keys(importedConfig).length == 0) {
-			throw new Error("Invalid ECF configuration")
+
+			// if from metadata, getting it by using Collection API provided by addCollection's function param
+			if (configFromMetadata) {
+				const configFieldName = pluginConfig.configDataField || defaultConfigFieldName;
+				const dataFieldConfig = eleventyCollectionApi.getAll()[0].data[configFieldName];
+				if (dataFieldConfig === undefined || dataFieldConfig === null) {
+					throw new Error(`ECF configuration collection "${configFieldName}" not detected`)
+				}
+				finalPluginConfig = dataFieldConfig;
+			}
+			if (!finalPluginConfig || Object.keys(finalPluginConfig).length == 0) {
+				throw new Error("Invalid ECF configuration")
+			}
+
+			if (Object.prototype.hasOwnProperty.call(finalPluginConfig, "items"))
+				finalPluginConfig = finalPluginConfig.items;
+
+			finalPluginConfigComputed = true;
+			return finalPluginConfig;
 		}
 
-		if (Object.prototype.hasOwnProperty.call(importedConfig, "items"))
-			importedConfig = importedConfig.items;
+	}
+
+	/* Processes all entries in all configured collections for unique field values,
+	 * then puts the final filter config into the 'ecfFilters' collection */
+	eleventyConfig.addCollection("ecfData", function(api) {
+		let config = getFinalConfig(api);
 
-		const ecfFiltersCollection = {};
-		importedConfig.forEach(function(collectionConfig) {
-			let { collection, filters } = collectionConfig;
+		const out = {};
+		config.forEach(function(filterCollectionConfig) {
+			let { collection: collectionName, filters } = filterCollectionConfig;
 			// making sure we're not making config collection edits in-place.
 			let filterConfig = configFromMetadata ? JSON.parse(JSON.stringify(filters)) : filters;
 
@@ -58,35 +97,48 @@ function ecfPlugin(eleventyConfig, pluginConfig = null) {
 			for (const filter of filterConfig) {
 				filter.values = new Set();
 			}
-			const entries = api.getFilteredByTag(collection);
-			entries.forEach(entry => {
+			const entries = api.getFilteredByTag(collectionName);
+			out[collectionName] = {};
+			out[collectionName].items = entries.map(entry => {
+				let ecfDataEntry = {};
 				for (const filter of filterConfig) {
+					ecfDataEntry[filter.field] = entry.data[filter.field];
+					ecfDataEntry["ecf_id"] = ecfResolveId(entry, filterCollectionConfig.identifyingField || defaultIdentifyingField).toString();
+
 					switch (filter.type) {
 						case "radio": {
 							let value = entry.data[filter.field];
-							let strValue = typeof value !== 'string' ? value.toString() : value;
-							filter.values.add(strValue);
+							if (value) {
+								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)
+								if (value) {
+									let strValue = typeof value !== 'string' ? value.toString() : value;
+									filter.values?.add(strValue)
+								}
 							});
 							break;
 						}
 					}
 				}
+				return ecfDataEntry;
 			});
 
 			// 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;
+			out[collectionName].filters = filterConfig;
+			out[collectionName].identifyingField = filterCollectionConfig.identifyingField || defaultIdentifyingField;
 		});
-		return ecfFiltersCollection;
+		return out;
 	});
+
+	eleventyConfig.addFilter('ecfResolveId', ecfResolveId);
 }
 
 module.exports = ecfPlugin;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "eleventy-plugin-filter-page",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "11ty plugin to create collection filter pages",
   "main": "dist/ecf.plugin.js",
   "files": [