Skip to content
This repository has been archived by the owner on Apr 20, 2022. It is now read-only.

radiocity/twig-html-loader

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

52 Commits
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

twig-html-loader

A loader for webpack that allows compiling twig templates into html string.

Getting Started

To begin, you'll need to install twig-html-loader:

npm install twig-html-loader --save-dev

Add twig template to your sources:

var html = require('./index.twig');

Then add the loader to your webpack config. For example:

module.exports = {
  // ...
  rules: [
    // ...
    {
      test: /\.twig$/,
      use: [
        'raw-loader',
        {
          loader: 'twig-html-loader',
          options: {
            data: {}
          }
        }
      ]
    }
    // ...
  ]
};

Using with html-webpack-plugin

Install plugin:

npm install html-webpack-plugin --save-dev

Improve your config:

const HtmlWebpackPlugin = require('html-webpack-plugin');
// ...
module.exports = {
  // ...
  rules: [
    // ...
    {
      test: /\.twig$/,
      use: [
        'raw-loader',
        'twig-html-loader'
      ]
    }
    // ...
  ],
  plugins: [
    // ...
    new HtmlWebpackPlugin({
      template: 'index.twig'
    })
  ]
};

Options

Name Type Default Description
cache boolean false Enables the Twigjs cache
data object or function(context) {} The data that is exposed in the templates. Function should return an object
debug boolean false Enables debug info logging
trace boolean false Enables tracing info logging
namespaces object undefined Add special template path notation (ex.: @namespace_name/template_path)
functions object undefined Extends Twig with custom functions
filters object undefined Extends Twig with custom filters
tests object undefined Extends Twig with custom tests
extend function(Twig) undefined Extends Twig with custom tags and more

Watch data from files

module.exports = {
  // ...
  rules: [
    // ...
    {
      test: /\.twig$/,
      use: [
        'raw-loader',
        {
          loader: 'twig-html-loader',
          options: {
            data: (context) => {
              const data = path.join(__dirname, 'data.json');
              context.addDependency(data); // Force webpack to watch file
              return context.fs.readJsonSync(data, { throws: false }) || {};
            }
          }
        }
      ]
    }
    // ...
  ]
};

Do not use require function due to file caching.

Namespaces

If the application defines lots of templates and stores them in deep nested directories, you may consider using namespaces, which create shortcuts to template directories. The registered namespace should be defined with @ prefix or :: postfix when using it in templates.

module.exports = {
  // ...
  rules: [
    // ...
    {
      test: /\.twig$/,
      use: [
        'raw-loader',
        {
          loader: 'twig-html-loader',
          options: {
            namespaces: {
              'layouts': 'path/to/layouts',
              'components': 'path/to/components',
            }
          }
        }
      ]
    }
    // ...
  ]
};
{# path/to/layouts/common.twig #}
<h1>{% block title %}{% endblock %}</h1>
{# path/to/components/greeting.twig #}
Hello, John Doe!
{# your-template.twig #}
{% extends "layouts::common.twig" %}
{% block title %}
  {{ include('@components/greeting.twig') }}
{% endblock %}

Custom functions, filters, tests and tags

You can use functions, filters, tests and extend options to extend Twig. See here for adding custom functions, filters and tests, and here for adding custom tags.

module.exports = {
  // ...
  rules: [
    // ...
    {
      test: /\.twig$/,
      use: [
        'raw-loader',
        {
          loader: 'twig-html-loader',
          options: {
            functions: {
              repeat(value, times) {
                return new Array(times + 1).join(value);
              }
            },
            filters: {
              backwords(value) {
                return value.split(' ').reverse().join(' ');
              }
            },
            tests: {
              theAnswer(value) {
                return value === 42;
              }
            },
            extend(Twig) {
              Twig.exports.extendTag({
                type: 'echo',
                regex: /^echo\s+(.+)$/,
                next: [],
                open: true,
                compile: function (token) {
                  var expression = token.match[1];

                  token.stack = Twig.expression.compile.apply(this, [{
                    type: Twig.expression.type.expression,
                    value: expression
                  }]).stack;

                  delete token.match;
                  return token;
                },
                parse: function (token, context, chain) {
                  return {
                    chain: false,
                    output: Twig.expression.parse.apply(this, [token.stack, context])
                  };
                }
              });
            }
          }
        }
      ]
    }
    // ...
  ]
};
{{ repeat('_.', 10) }}
{# output: _._._._._._._._._._. #}

{{ 'a quick brown fox'|backwords }}
{# output: fox brown quick a #}

{% if 42 is theAnswer %}42{% endif %}
{# output: 42 #}

{% echo 'hello world' %}
{# output: hello world #}

Alternatives

twig-loader

License

MIT (http://www.opensource.org/licenses/mit-license.php)