add an option to disable strict name checking (closes #16)

chocolateboy · chocolateboy · commit a72ca0eab3bb · 2018-09-20T12:50:46.000+01:00
diff --git a/README.md b/README.md
@@ -7,7 +7,7 @@
 Let's say we have a base template:
 
 `base.html`
-```html
+```xml
 <html>
     <head>
         <title><block name="title"> — Github</block></title>
@@ -46,7 +46,7 @@ posthtml([require('posthtml-extend')({
 ```
 
 The final HTML will be:
-```html
+```xml
 <html>
     <head>
         <title>How to use posthtml-extend</title>
@@ -76,7 +76,7 @@ posthtml([require('posthtml-extend')()]).process(html).then(function (result) {
 ```
 
 The final HTML will be:
-```html
+```xml
 <html>
     <head>
         <title>How to use posthtml-extend — Github</title>
@@ -88,8 +88,15 @@ The final HTML will be:
 </html>
 ```
 
-### Plugins
-You can also include [other PostHTML plugins](http://posthtml.github.io/posthtml-plugins/) in your templates.
+## Options
+
+### encoding
+
+The encoding of the parent template. Default: "utf8".
+
+### plugins
+
+You can include [other PostHTML plugins](http://posthtml.github.io/posthtml-plugins/) in your templates.
 Here is an example of using [posthtml-expressions](https://github.com/posthtml/posthtml-expressions), which allows to use variables and conditions:
 
 ```js
@@ -115,7 +122,7 @@ posthtml([require('posthtml-extend')(options)]).process(html).then(function (res
 ```
 
 The final HTML will be:
-```html
+```xml
 <html>
     <head>
         <title>How to use posthtml-extend — Github</title>
@@ -126,3 +133,24 @@ The final HTML will be:
     </body>
 </html>
 ```
+
+### root
+
+The path to the root template directory. Default: "./".
+
+### strict
+
+Whether the plugin should disallow undeclared block names. Default: true.
+
+By default, posthtml-extend raises an exception if an undeclared block name is encountered. This can be useful for troubleshooting (i.e. detecting typos in block names), but
+there are cases where "forward declaring" a block name as an extension point for downstream templates is useful, so this restriction can be lifted by setting the `strict`
+option to a false value:
+
+```javascript
+const extend = require('posthtml-extend');
+
+const root = './src/html';
+const options = { root, strict: false };
+
+posthtml([extends(options)]).then(result => console.log(result.html));
+```
diff --git a/lib/extend.es6 b/lib/extend.es6
@@ -15,6 +15,7 @@ export default (options = {}) => {
         options.encoding = options.encoding || 'utf8';
         options.root = options.root || './';
         options.plugins = options.plugins || [];
+        options.strict = Object.prototype.hasOwnProperty.call(options, 'strict') ? !!options.strict : true;
 
         tree = handleExtendsNodes(tree, options, tree.messages);
 
@@ -41,7 +42,7 @@ function handleExtendsNodes(tree, options, messages) {
         let layoutTree = handleExtendsNodes(applyPluginsToTree(parseToPostHtml(layoutHtml), options.plugins), options, messages);
 
         extendsNode.tag = false;
-        extendsNode.content = mergeExtendsAndLayout(layoutTree, extendsNode);
+        extendsNode.content = mergeExtendsAndLayout(layoutTree, extendsNode, options.strict);
         messages.push({
             type: 'dependency',
             file: layoutPath,
@@ -59,7 +60,7 @@ function applyPluginsToTree(tree, plugins) {
 }
 
 
-function mergeExtendsAndLayout(layoutTree, extendsNode) {
+function mergeExtendsAndLayout(layoutTree, extendsNode, strictNames) {
     const layoutBlockNodes = getBlockNodes(layoutTree);
     const extendsBlockNodes = getBlockNodes(extendsNode.content);
 
@@ -79,8 +80,10 @@ function mergeExtendsAndLayout(layoutTree, extendsNode) {
         delete extendsBlockNodes[layoutBlockName];
     }
 
-    for (let extendsBlockName of Object.keys(extendsBlockNodes)) {
-        throw getError(errors.UNEXPECTED_BLOCK, extendsBlockName);
+    if (strictNames) {
+        for (let extendsBlockName of Object.keys(extendsBlockNodes)) {
+            throw getError(errors.UNEXPECTED_BLOCK, extendsBlockName);
+        }
     }
 
     return layoutTree;
diff --git a/package.json b/package.json
@@ -6,10 +6,10 @@
   "author": "Kirill Maltsev <maltsevkirill@gmail.com>",
   "license": "MIT",
   "scripts": {
-    "compile": "rm -f lib/*.js && node_modules/.bin/babel -d lib/ lib/",
-    "lint": "node_modules/.bin/eslint *.js lib/*.es6 test/",
+    "compile": "rm -f lib/*.js && babel -d lib/ lib/",
+    "lint": "eslint *.js lib/*.es6 test/",
     "pretest": "npm run lint && npm run compile",
-    "test": "node_modules/.bin/_mocha --compilers js:babel-core/register --check-leaks",
+    "test": "_mocha --compilers js:babel-core/register --check-leaks",
     "prepublish": "npm run compile"
   },
   "keywords": [
diff --git a/test/extend.js b/test/extend.js
@@ -200,6 +200,29 @@ describe('Extend', () => {
             '[posthtml-extend] Unexpected block "head"'
         );
     });
+
+
+    it('should not throw an error for an unexpected <block> if `strict` is false', () => {
+        mfs.writeFileSync('./layout.html', '<h1>Welcome to 3 Pages!</h1><block name="body"></block>');
+        mfs.writeFileSync(
+            './page1.html',
+            `<extends src="layout.html">
+                <block name="body">
+                    <form name="login">
+                        <block name="submit-button">
+                            <input type="submit" disabled="disabled" />
+                        </block>
+                    </form>
+                </block>
+            </extends>`
+        );
+
+        const page3 = '<extends src="page1.html"><block name="submit-button"><input type="submit" /></block></extends>';
+        const want = '<h1>Welcome to 3 Pages!</h1><form name="login"><input type="submit"></form>';
+
+        return init(page3, { strict: false })
+            .then(html => expect(html).toBe(want));
+    });
 });
 
 describe('Messages', () => {
