Nuns Playing Monopoly

    twing
    TypeScript icon, indicating that this package has built-in type declarations

    5.1.2 • Public • Published

    Twing

    NPM version Build Status Coverage percentage Donate

    First-class Twig engine for Node.js

    Philosophy behind Twing

    We believe that a first-class Twig engine should be able to render any template to the exact same result as the official PHP engine. That means that it should implement 100% of the syntax defined by the language specifications and that it should render that syntax using PHP logic.

    We also believe that a first-class Twig engine should be able to catch-up easily when Twig specifications evolve. Its code architecture and philosophy should then be as close as possible as the PHP implementation.

    Finally, we believe that a first-class Twig engine should allow users to build on their experience with TwigPHP and get support from the huge community that comes with it.

    That's what Twing is. A maintainability-first engine that pass 100% of the TwigPHP integration tests, is as close as possible to its code structure and expose an as-close-as-possible API.

    Prerequisites

    Twing needs at least node.js 8.0.0 to run.

    Installation

    The recommended way to install Twing is via npm:

    npm install twing --save

    Basic API Usage

    const {TwingEnvironment, TwingLoaderArray} = require('twing');
    
    let loader = new TwingLoaderArray({
        'index.twig': 'Hello {{ name }}!'
    });
    let twing = new TwingEnvironment(loader);
    
    twing.render('index.twig', {name: 'Fabien'}).then((output) => {
        // do something with the output
    });

    Usage with Express

    Twing and Express work quite well together. Have a look at the documentation for an example of usage with Express.

    Browser support

    Starting with version 2.0.0, Twing can be used in web browsers with very few compromise. Filesystem components are obviously not available (namely filesystem loader and cache) but everything else is fully supported.

    Module bundler

    Module bundlers will automatically grab the browser-specific flavor of Twing when Twing module is imported. Either const {TwingEnvironment} = require('twing'); or import {TwingEnvironment} from 'twing'; will work in both node.js and the browser - once bundled in the latter case.

    Script tag

    Use jsdelivr CDN to include Twing in your HTML document:

    <script src="https://cdn.jsdelivr.net/npm/twing/dist/lib.min.js"></script>

    Once loaded by the browser, Twing is available under the global Twing variable.

    Twig specifications implementation

    Twing aims at implementing Twig specifications perfectly, without compromise. This is not an easy task due to the nature of Twig specifications: they don't exist officially and can only be deduced from the public documentation, the source code documentation and the test suite of the PHP reference implementation. It sometimes happens that something that was not part of either the documentations or the test suite suddenly becomes part of the specifications like the filter tag or the macros rework issues, putting Twing and all other non-reference implementations in the uncomfortable position of having to deal with a potential breaking change. Since Twig's team doesn't plan on releasing some official specifications for the language, we can't expect the problem to be solved anytime soon.

    Twing's strategy here is to stick strictly to Semantic Versioning rules and never introduce a breaking change into a minor version - its extensive test suite with 100% code coverage guarantees that. Twig teams's mistakes will be managed by either issuing a known issue, if the mistake is trivial, or bumping to a new major version, if it is not.

    Compatibility chart

    Here is the compatibility chart between minor versions of Twing and Twig specifications levels, along with a summary of notable features provided by each Twig specifications level. Note that Twig minor versions don't always provide new language-related features (because of Twig's team perpetuating the confusion between Twig and their reference implementation, TwigPHP).

    Twing version Twig specifications level Notable features
    3.0 2.11 Macros scoping
    2.3 2.10 spaceless, column, filter, map and reduce filters, apply tag, line whitespace trimming whitespace control modifier
    2.2 2.6 deprecated tag
    1.3 2.5 spaceless and block-related deprecations
    1.0 2.4

    It is highly recommended to always use the latest version of Twing available as bug fixes will always target the latest version.

    Known issues

    You can find the list of known issues of Twing regarding Twig specifications implementation here. Note that known issues are guaranteed to be addressed in the next major version bump of Twing.

    More information

    Read the documentation for more information.

    Related projects

    • gulp-twing: Compile Twig templates with gulp. Build upon Twing.
    • twing-loader: Webpack loader that compiles Twig templates using Twing.

    Contributing

    • Fork this repository
    • Code
    • Implement tests using tape
    • Issue a pull request keeping in mind that all pull requests must reference an issue in the issue queue

    License

    Copyright © 2018 Eric MORAND. Released under the 2-Clause BSD License.

    Install

    npm i twing

    DownloadsWeekly Downloads

    7,079

    Version

    5.1.2

    License

    BSD-2-Clause

    Unpacked Size

    2.84 MB

    Total Files

    773

    Last publish

    Collaborators

    • ericmorand