@fiad/twig-addons

@fiad/twig-addons

A collection of filters and functions for Twig (JS)

Get started

Installation

npm i @fiad/twig-addons

Usage

Basic

import twig from 'twig'
import twigAddons from '@fiad/twig-addons'

const engine = twigAddons(twig)

engine.renderFile('path/to/template.twig', { foo: 'bar' }, (err, html) => {
  fs.writeFileSync('path/to/template.html', html)
})

With Express

import express from 'express'
import twig from 'twig'
import twigAddons from '@fiad/twig-addons'

const app = express()

app.engine('twig', twigAddons(twig).__express)

Filters list

map

A porting of JavaScript's Array.prototype.map().

Definition:

map(values, args)

Argument	Description	Type
values	The original values	array
args	The array of arguments passed to the filter	array

Here below the supported filter arguments:

Argument	Description	Type
handler	The mapping handler	string

ℹ️ Please note that the handler argument should be a stringified arrow function evaluable by eval().

Usage:

// mock
{
  "guests": [
    { "firstname": "John", "lastname": "Doe", /* ... */ },
    { "firstname": "Jane", "lastname": "Doe", /* ... */ }
  ]
}

<p class="guests">
  {{ guests|map('({ firstname, lastname }) => `${firstname} ${lastname}`')|join(', ') }}
</p>

⚠️ Since this filter involves the usage of eval(), it's recommended to use it for static sites generation purposes only, so that the stringified JavaScript execution will be limited to the development environment. Look here to learn more.

reduce

A porting of JavaScript's Array.prototype.reduce().

Definition:

reduce(values, args)

Argument	Description	Type
values	The original values	array
args	The array of arguments passed to the filter	array

Here below the supported filter arguments:

Argument	Description	Type
reducer	The reducing handler	string
carry	The initial reduced value	any

ℹ️ Please note that the reducer argument should be a stringified arrow function evaluable by eval().

Usage:

// mock
{
  "cart": [
    { "price": 10, /* ... */ },
    { "price": 20, /* ... */ },
    { "price": 15, /* ... */ }
  ]
}

<p class="total">
  {{ cart|reduce('(total, { price }) => (total + price)', 0) }} €
</p>

⚠️ Since this filter involves the usage of eval(), it's recommended to use it for static sites generation purposes only, so that the stringified JavaScript execution will be limited to the development environment. Look here to learn more.

remap

It allows you to remap an object with different keys and eventually discard its needless properties.

Definition:

remap(value, args)

Argument	Description
value	The original object to be remapped
args	The array of arguments passed to the filter

Here below the supported filter arguments:

Argument	Description
keys	The list of key replacements, formatted like "old:new"
options	A configuration object containing additional settings

The options argument supports the following properties:

Property	Description	Default
discardUnmentioned	If true, any properties not included in the keys argument will be omitted from the returned object	false

Usage:

Source

// mock
{
  "article_id": "post-1",
  "article_type": "news",
  "article_title": "Lorem ipsum.",
  "article_text": "Ea duis sint ad ipsum in dolor quis consequat.",
  "article_category": "foo"
}

{# components/article.twig #}
<article>
  <h1>{{ title }}</h1>
  <p>{{ description }}</p>
</article>


{# templates/page.twig #}
{% set data = mock|remap([
  'article_title:title',
  'article_text:description'
], {
  discardUnmentioned: true
}) %}

<main>
  {% include 'components/article.twig' with data %}
</main>

Result

<main>
  <article>
    <h1>Lorem ipsum.</h1>
    <p>Ea duis sint ad ipsum in dolor quis consequat.</p>
  </article>
</main>

Functions list

html_classes

A porting of Twig's html_classes. Look at the official documentation to learn more about usage.

Definition:

html_classes(...classes)

tag_attributes

It dynamically builds the stringified attributes list of an html tag starting from a key-value object. It supports you in adopting a standard and comfortable parametric system to pass attributes to a component directly from the include statement.

Definition:

tag_attributes(attributes, defaults)

Argument	Description
attributes	The attributes object to be parsed
defaults (optional)	The default attributes to extend, useful when you need to merge with some predefined properties (use this argument instead of Twig built-in merge filter to ensure proper attribute parsing)

Usage:

Source

// mock
{
  "link": {
    "label": "Lorem ipsum",
    "attributes": {
      "class": "link--primary",
      "href": "https://domain.ext/slug",
      "target": "_blank"
    }
  }
}

{# components/link.twig #}

{% set defaults = {
  class: 'link',
  target: '_self'
} %}

<a {{ tag_attributes(attributes, defaults) }}>
  <span class="link__label">{{ label }}</span>
</a>

Result

<a class="link link--primary" href="https://domain.ext/slug" target="_blank">
  <span class="link__label">Lorem ipsum</span>
</a>

ℹ️ Please note that the default class attribute wasn't overridden, as did the target one instead, but the default value and the overriding one have been concatenated. This is to avoid the accidental breaking of some of the component basic styles and behaviors associated with the default class(es) eventually defined within the component partial.