refactor(shortcodes)!: replace shortcodes with functions and filters #34
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,24 @@ | ||
| # Extend filter examples | ||
|
|
||
| <p style="font-size: 2rem"> | ||
| <img | ||
| style="margin:2rem; width:8rem; height:8rem;" | ||
| align="center" | ||
| width="128" | ||
| height="128" | ||
| alt="Eleventy Logo" | ||
| src="https://camo.githubusercontent.com/124e337fb005b0e70eb3758b431b051eaf5419b3a709062fbcce6d661a6ea116/68747470733a2f2f7777772e313174792e6465762f696d672f6c6f676f2d6769746875622e737667">+ | ||
| <img | ||
| style="margin:2rem; width:8rem; height:8rem;" | ||
| align="center" | ||
| width="128" | ||
| height="128" | ||
| alt="Twig.js Logo" | ||
| src="https://user-images.githubusercontent.com/3282350/29336704-ab1be05c-81dc-11e7-92e5-cf11cca7b344.png"> | ||
| </p> | ||
|
|
||
| ## Side note: | ||
|
|
||
| Please read the [Twig](https://twig.symfony.com/doc/2.x/advanced.html#extending-twig) Documentation about how to extend twig properly first. Checkout the [Twig.js] documentation for `extendFunction()` as well. Also notice that functions should be used for content generation and frequent use whereas filters are more for value transformations in general. | ||
|
There was a problem hiding this comment. The “extending Twig” link points to version 2.x. The latest Twig version is 3.x. There was a problem hiding this comment. There is a lonely |
||
|
|
||
| _...in the making_ | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,31 @@ | ||
| const twig = require("twig"); | ||
|
|
||
| /** | ||
| * This utilizes twigs extendFilter | ||
| * | ||
| * @param {import("@11ty/eleventy").UserConfig} eleventyConfig | ||
| * @param {import("../plugin").USER_OPTIONS} userOptions | ||
| * @param {import("../plugin").FILTER} filter | ||
| */ | ||
| const extendTwig = (eleventyConfig, userOptions, filter) => { | ||
| twig.extendFilter(filter.symbol, (...args) => { | ||
| return filter.callback(eleventyConfig, userOptions, ...args); | ||
| }); | ||
| }; | ||
|
|
||
| /** | ||
| * Iterates over all filters and add symbols with | ||
| * their corresponding callbacks to twig | ||
| * | ||
| * @param {import("@11ty/eleventy").UserConfig} eleventyConfig | ||
| * @param {import("../plugin").USER_OPTIONS} userOptions | ||
| */ | ||
| module.exports = (eleventyConfig, userOptions) => { | ||
| (userOptions.twig?.filter || []).forEach((filter) => { | ||
|
There was a problem hiding this comment. You could switch to early returns to make the code more readable and to add error messages: if (!userOptions.twig?.filter) {
return;
}
if (!Array.isArray(userOptions.twig.filter)) {
// Log error to console…
return;
}
userOptions.twig.filter.forEach(…There was a problem hiding this comment.
|
||
| try { | ||
| extendTwig(eleventyConfig, userOptions, filter); | ||
| } catch (error) { | ||
| console.log(error); | ||
| } | ||
| }); | ||
| }; | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,126 @@ | ||
| # Extend function examples | ||
|
|
||
| <p style="font-size: 2rem"> | ||
| <img | ||
| style="margin:2rem; width:8rem; height:8rem;" | ||
| align="center" | ||
| width="128" | ||
| height="128" | ||
| alt="Eleventy Logo" | ||
| src="https://camo.githubusercontent.com/124e337fb005b0e70eb3758b431b051eaf5419b3a709062fbcce6d661a6ea116/68747470733a2f2f7777772e313174792e6465762f696d672f6c6f676f2d6769746875622e737667">+ | ||
| <img | ||
| style="margin:2rem; width:8rem; height:8rem;" | ||
| align="center" | ||
| width="128" | ||
| height="128" | ||
| alt="Twig.js Logo" | ||
| src="https://user-images.githubusercontent.com/3282350/29336704-ab1be05c-81dc-11e7-92e5-cf11cca7b344.png"> | ||
| </p> | ||
|
|
||
| ## Side note: | ||
|
|
||
| Please read the [Twig](https://twig.symfony.com/doc/2.x/advanced.html#extending-twig) Documentation about how to extend twig properly first. Checkout the [Twig.js] documentation for `extendFunction()` as well. Also notice that functions should be used for content generation and frequent use whereas filters are more for value transformations in general. | ||
|
There was a problem hiding this comment. The “extending Twig” link points to version 2.x. The latest Twig version is 3.x. There was a problem hiding this comment. There is a lonely |
||
|
|
||
| ## `mix` | ||
|
|
||
| Its most likely that your project uses hashed assets. Therefore you have to include them somehow dynamically and Eleventy as well as Twig should be aware of this. | ||
|
|
||
|
|
||
| Lets define a function `mix()` which returns the hashed path to the given non hashed asset like: | ||
|
|
||
|
|
||
| ```twig | ||
| {{ mix("/path/to/unhased/asset.extension") }} --> will result in /path/to/hashed/asset.hash.extension | ||
| ``` | ||
|
|
||
| There is an example implementation in `examples/mix.js`. To activate that implementation you have to add this module to the `userOptions.twig.functions` in your Eleventy configuration file and define the `userOptions.mixManifest` as well as the `userOptions.dir.output` property optionally like: | ||
|
|
||
| ```js | ||
| const mix = require("@factorial/eleventy-plugin-twig/functions/examples/mix"); | ||
|
There was a problem hiding this comment. The module path is missing |
||
|
|
||
| const userOptions = { | ||
| twig: { | ||
| functions: [ | ||
| symbol: "mix", | ||
| callback: mix, | ||
| ] | ||
|
Comment on lines
+41
to
+44
There was a problem hiding this comment.
functions: [
{
symbol: "mix",
callback: mix,
}
] |
||
| } | ||
| mixManifest: "mixManifest.json" // path relative to the output directory | ||
| dir: { | ||
| output: "build" // optionally, eleventy has a default output folder "_site", see https://www.11ty.dev/docs/config/#output-directory | ||
|
|
||
| } | ||
| } | ||
| ``` | ||
|
|
||
| ## `asset_path` | ||
|
|
||
| If you have to reference lots of assets (e.g. images etc...) or have different environments like storybook / miyagi / prod / staging / dev etc. then its sometimes helpful to define a helper function like `asset_path()` with returns the path to your assets folder in the specific environment. | ||
|
There was a problem hiding this comment. Typos:
|
||
|
|
||
| For this to work lets define a `asset_path()` function which prefixes a given path with the `userOptions.assets.base` path like: | ||
|
|
||
|
|
||
| ```twig | ||
| {{ asset_path()/subfolder/filename.extension }} --> will result in /path/to/your/assets/subfolder/filename.extension | ||
|
There was a problem hiding this comment. The path should be outside of the curly brace variable print thingy: {{ asset_path() }}/subfolder/filename.extension |
||
| ``` | ||
|
|
||
| There is an example implementation in `examples/assetPath.js`. To activate that implementation you have to add this module to the `userOptions.twig.functions` in your Eleventy configuration file and define the `userOptions.assets.base` property like: | ||
|
|
||
| ```js | ||
| const assetPath = require("@factorial/eleventy-plugin-twig/functions/examples/assetPath"); | ||
|
There was a problem hiding this comment. The module path is missing |
||
|
|
||
| const userOptions = { | ||
| twig: { | ||
| functions: [ | ||
| symbol: "asset_path", | ||
| callback: assetPath, | ||
| ] | ||
|
Comment on lines
+70
to
+73
There was a problem hiding this comment.
functions: [
{
symbol: "asset_path",
callback: assetPath,
}
] |
||
| }, | ||
| assets: { | ||
| base: "assets" // base folder relative to the build folder; could be defined by environmetal variables for different szenarios as well | ||
| } | ||
| } | ||
| ``` | ||
|
|
||
| ## `image` | ||
|
|
||
| Eleventy comes with a great responsive image plugin called [@11ty/eleventy-img](https://github.com/11ty/eleventy-img). This autogenerates different file formats and sizes for those images included in your templates. | ||
|
|
||
| Lets define a `image()` function which returns a proper `<picture>` element with `<source>` elements: | ||
|
|
||
|
|
||
| ```twig | ||
| {{ image("src", "alt", "classes") }} --> will result in a <picture> element with different <source> elements for each format and defined widths | ||
| ``` | ||
|
|
||
| First install the latest `@11ty/eleventy-img` release as a node module with `yarn`: | ||
|
|
||
|
|
||
| ```sh | ||
| yarn add --dev @11ty/eleventy-img | ||
| ``` | ||
|
|
||
| or `npm`: | ||
|
|
||
| ```sh | ||
| npm install --save-dev @11ty/eleventy-img | ||
| ``` | ||
|
|
||
| You can find an example implementation in `examples/image.js`. To activate that implementation you have to add this module to the `userOptions.twig.functions` in your eleventy configuration file, as well as a couple of other necessary properties like: | ||
|
|
||
|
|
||
| ```js | ||
| const image = require("@factorial/eleventy-plugin-twig/functions/examples/image"); | ||
|
There was a problem hiding this comment. The module path is missing |
||
|
|
||
| const userOptions = { | ||
| twig: { | ||
| function: [ | ||
| symbol: "image", | ||
| callback: image, | ||
| ] | ||
|
Comment on lines
+110
to
+113
There was a problem hiding this comment.
functions: [
{
symbol: "image",
callback: image,
}
] |
||
| }, | ||
| assets: { | ||
| root: "src", // path to the root folder from projects root (e.g. src) | ||
| base: "assets", // base path for assets relative to the root folder (e.g. assets) | ||
| images: "images", // path to the image folder relative to the base (e.g. images) | ||
| }, | ||
| images: { | ||
| widths: [300, 600, 900], // those image sizes will be autogenereated / aspect-ratio will be respected | ||
| formats: ["webp", "avif"], // jpeg/avif/webp/png/gif | ||
| additionalAttributes: "" // optionally - those attributes will be added to the image element | ||
| } | ||
| } | ||
| ``` | ||
File renamed without changes.
File renamed without changes.
File renamed without changes.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,31 @@ | ||
| const twig = require("twig"); | ||
|
|
||
| /** | ||
| * This utilizes twigs extendFunction | ||
| * | ||
| * @param {import("@11ty/eleventy").UserConfig} eleventyConfig | ||
| * @param {import("../plugin").USER_OPTIONS} userOptions | ||
| * @param {import("../plugin").FUNCTION} func | ||
| */ | ||
| const extendTwig = (eleventyConfig, userOptions, func) => { | ||
| twig.extendFunction(func.symbol, (...args) => { | ||
| return func.callback(eleventyConfig, userOptions, ...args); | ||
| }); | ||
| }; | ||
|
|
||
| /** | ||
| * Iterates over all functions and add symbols with | ||
| * their corresponding callbacks to twig | ||
| * | ||
| * @param {import("@11ty/eleventy").UserConfig} eleventyConfig | ||
| * @param {import("../plugin").USER_OPTIONS} userOptions | ||
| */ | ||
| module.exports = (eleventyConfig, userOptions) => { | ||
| (userOptions.twig?.functions || []).forEach((func) => { | ||
|
There was a problem hiding this comment. You could switch to early returns to make the code more readable and to add error messages: if (!userOptions.twig?.functions) {
return;
}
if (!Array.isArray(userOptions.twig.functions)) {
// Log error to console…
return;
}
userOptions.twig.functions.forEach(… |
||
| try { | ||
| extendTwig(eleventyConfig, userOptions, func); | ||
| } catch (error) { | ||
| console.error(error); | ||
| } | ||
| }); | ||
| }; | ||
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
twig.extendFunction()andtwig.extendFilter()is done automatically by the plugin. I don’t think it is necessary to mention the “internals” here.