Allow tags at block-level if specified

Fixes gh-289

docs/docs/extending.html

@@ -95,17 +95,33 @@ <h4>Arguments</h4>
   {% endif %}{% endfor %}
 
   <section id="ends" class="doc">
-      <h3>ends</h3>
+    <h3>ends</h3>
 
-      <p>Controls whether or not a tag must have an <code data-language="swig">{% raw %}{% end[tagName] %}{% endraw %}</code> declared after usage in templates.</p>
+    <p>Controls whether or not a tag must have an <code data-language="swig">{% raw %}{% end[tagName] %}{% endraw %}</code> declared after usage in templates.</p>
 
-      <pre><code data-language="js">exports.ends = true;
+    <pre><code data-language="js">exports.ends = true;
 // => A template that fails to close this tag will throw an Error.</code></pre>
 
-      <pre><code data-language="js">exports.ends = false;
+    <pre><code data-language="js">exports.ends = false;
 // => A template attempts close this tag will throw an Error.</code></pre>
    </section>
 
+   <section id="blockLevel" class="doc">
+     <h3>blockLevel</h3>
+
+     <p>Allow the tag to be written outside of <code data-language="swig">{% raw %}{% block &lt;name&gt; %}{% endblock %}{% endraw %}</code> tags when extending a parent template.</p>
+
+     <pre><code data-language="js">exports.blockLevel = true;</code></pre>
+     <pre><code data-language="swig">{% raw %}{% extends "foo" %}
+{% mytag foo bar baz %}
+// Normally this will be ignored, but since we allowed it to be block-level,
+// it will be included in the fully-parsed template.
+
+{% block content %}
+  ...
+{% endblock %}{% endraw %}</code></pre>
+   </section>
+
   {% for prop in properties %}
     {% if prop.isEnum %}
     <section id="{{ prop.name }}" class="doc">
@@ -159,6 +175,7 @@ <h3>{{ prop.name }}</h3>
       <li><a href="#parse">parse</a></li>
       <li><a href="#compile">compile</a></li>
       <li><a href="#ends">ends</a></li>
+      <li><a href="#blockLevel">blockLevel</a></li>
       <li><a href="#TYPES">Token Types</a></li>
     </ol>
   </li>

lib/parser.js

@@ -539,6 +539,7 @@ exports.parse = function (source, opts, tags, filters) {
      * @property {string} name The name of this tag.
      */
     return {
+      block: !!tags[tagName].block,
       compile: tag.compile,
       args: args,
       content: [],
@@ -581,13 +582,12 @@ exports.parse = function (source, opts, tags, filters) {
       stripNext = tagStripAfter.test(chunk);
       token = parseTag(chunk.replace(tagStrip, ''), line);
       if (token) {
-        switch (token.name) {
-        case 'extends':
+        if (token.name === 'extends') {
           parent = token.args.join('').replace(/^\'|\'$/g, '').replace(/^\"|\"$/g, '');
-          break;
-        case 'block':
+        }
+
+        if (token.block) {
           blocks[token.args.join('')] = token;
-          break;
         }
       }
       if (inRaw && !token) {

lib/swig.js

@@ -236,19 +236,22 @@ exports.Swig = function (opts) {
   /**
    * Add a custom tag. To expose your own extensions to compiled template code, see <code data-language="js">swig.setExtension</code>.
    *
+   * For a more in-depth explanation of writing custom tags, see <a href="../extending/#tags">Custom Tags</a>.
+   *
    * @example
    * var tacotag = require('./tacotag');
-   * swig.setTag('tacos', tacotag.parse, tacotag.compile, tacotag.ends);
+   * swig.setTag('tacos', tacotag.parse, tacotag.compile, tacotag.ends, tacotag.blockLevel);
    * // => {% tacos %}Make this be tacos.{% endtacos %}
    * // => Tacos tacos tacos tacos.
    *
    * @param  {string} name      Tag name.
    * @param  {function} parse   Method for parsing tokens.
    * @param  {function} compile Method for compiling renderable output.
    * @param  {boolean} [ends=false]     Whether or not this tag requires an <i>end</i> tag.
+   * @param  {boolean} [blockLevel=false] If false, this tag will not be compiled outside of <code>block</code> tags when extending a parent template.
    * @return {undefined}
    */
-  this.setTag = function (name, parse, compile, ends) {
+  this.setTag = function (name, parse, compile, ends, blockLevel) {
     if (typeof parse !== 'function') {
       throw new Error('Tag "' + name + '" parse method is not a valid function.');
     }
@@ -260,7 +263,8 @@ exports.Swig = function (opts) {
     tags[name] = {
       parse: parse,
       compile: compile,
-      ends: ends || false
+      ends: ends || false,
+      block: !!blockLevel
     };
   };
 
@@ -346,6 +350,11 @@ exports.Swig = function (opts) {
    * @private
    */
   function remapBlocks(blocks, tokens) {
+    utils.each(blocks, function (block) {
+      if (block.name !== 'block') {
+        tokens.unshift(block);
+      }
+    });
     return utils.map(tokens, function (token) {
       var args = token.args ? token.args.join('') : '';
       if (token.name === 'block' && blocks[args]) {

lib/tags/block.js

@@ -22,3 +22,4 @@ exports.parse = function (str, line, parser, types) {
 };
 
 exports.ends = true;
+exports.block = true;

lib/tags/set.js

@@ -47,3 +47,5 @@ exports.parse = function (str, line, parser, types, stack) {
 
   return true;
 };
+
+exports.block = true;

tests/cases/extends_set.expectation.html

@@ -0,0 +1,6 @@
+Hi,
+
+bar
+
+Sincerely,
+Me

tests/cases/extends_set.test.html

@@ -0,0 +1,4 @@
+{% extends "./extends_base.html" %}
+{% set foo = "bar" %}
+
+{% block body %}{{ foo }}{% endblock %}