feat(engine-twig): add custom twing extensions (#1435)

* feat(engine-twig): add custom twing extensions

Closes: #1230

* docs(engine-twig): adding custom twing extensions documentation

Refs: #1230

Co-authored-by: Josef Bredreck <13408112+JosefBredereck@users.noreply.github.com>
Co-authored-by: Maximilian Franzke <787658+mfranzke@users.noreply.github.com>

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)

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<string, TwingExtensionInterface>)`
+- 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

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);
+        }
+      }
+    }
   },
 };