diff --git a/packages/docs/src/docs/advanced-config-options.md b/packages/docs/src/docs/advanced-config-options.md index bc74c780b..3804c5b30 100644 --- a/packages/docs/src/docs/advanced-config-options.md +++ b/packages/docs/src/docs/advanced-config-options.md @@ -399,3 +399,17 @@ Important details: } ] ``` + +## Pattern Engine-Twig +### loadExtensionFile +Adding custom TwingExtensions to `engine-twig` via setting a filename in + +```javascript +"engine": { + "twig": { + "loadExtensionFile": "" + } +} +``` + +- `loadExtensionFile`: filename in Patternlab root directory. Details: [engine-twig readme](https://github.com/pattern-lab/patternlab-node/blob/dev/packages/engine-twig/README.md) diff --git a/packages/engine-twig/README.md b/packages/engine-twig/README.md index 9d45fca95..91d78cc3c 100644 --- a/packages/engine-twig/README.md +++ b/packages/engine-twig/README.md @@ -16,3 +16,42 @@ Now that this engine uses a better Twig Javascript library, the following issues * [Verify maturity of Twig engine](https://github.com/pattern-lab/patternlab-node/issues/285) See https://github.com/pattern-lab/the-spec/issues/37 for more info. + +## Adding Custom Extensions + +Create a JS file in Pattern Lab root directory (e.g. `twingExtensions.js`) and set +```javascript +"engine": { + "twig": { + "loadExtensionFile": "twingExtensions.js" + } +} +``` +in `patternlab-config.json`. See [Editing the Configuration Options](https://patternlab.io/docs/editing-the-configuration-options/#heading-loadextensionfile) for more info. + +- this JS file must export a Map for `TwingEnvironment.addExtensions(extensions: Map)` +- Map will be added to the TwingEnvironment on startup + +### Example + +```javascript +// twingExtensions.js +const { TwingExtension, TwingFunction } = require('twing'); + +const extensionsMap = new Map(); + +class TestTwingExtension extends TwingExtension { + getFunctions() { + return [ + new TwingFunction('foobar', function (foo) { + return Promise.resolve(`function foobar called with param "${foo}"`); + }), + ]; + } +} +extensionsMap.set('TestTwingExtension', new TestTwingExtension()); + +module.exports = extensionsMap; +``` + +See https://nightlycommit.github.io/twing/advanced.html#creating-an-extension for more details on how to create extensions diff --git a/packages/engine-twig/lib/engine_twig.js b/packages/engine-twig/lib/engine_twig.js index 89dac691b..6a2aedeca 100644 --- a/packages/engine-twig/lib/engine_twig.js +++ b/packages/engine-twig/lib/engine_twig.js @@ -229,6 +229,26 @@ var engine_twig = { fileSystemLoader.addPath(namespaces[key], key); }); } + + // add twing extensions + if ( + config['engines'] && + config['engines']['twig'] && + config['engines']['twig']['loadExtensionsFile'] + ) { + const extensionsFile = path.resolve( + './', + config['engines']['twig']['loadExtensionsFile'] + ); + if (fs.pathExistsSync(extensionsFile)) { + try { + const extensionsMap = require(extensionsFile); + twing.addExtensions(extensionsMap); + } catch (e) { + console.error(e); + } + } + } }, };