rezgui / twigextensions-plugin
Register more Twig filters for your WinterCMS templates
Installs: 2
Dependents: 0
Suggesters: 0
Security: 0
Stars: 0
Watchers: 0
Forks: 27
Type:winter-plugin
Requires
- php: >=8.0.2
- composer/installers: ~1.0
- twig/intl-extra: ^3.4
- winter/storm: ~1.2.0
Requires (Dev)
- jakub-onderka/php-parallel-lint: ^0.9.2
- phpunit/phpunit: ^9.6
- squizlabs/php_codesniffer: 3.*
This package is auto-updated.
Last update: 2025-03-28 21:45:40 UTC
README
Twig extensions forked from vojtasvoboda/oc-twigextensions-plugin, is a plugin for WinterCMS adds new filter and functions to your templates. No other plugin dependencies.
Installation
Install plugin from CMS backend or by Composer:
composer require rezgui/wn-twigextensions-plugin
Than you can use newly added filters/functions at your templates:
<h1 class="heading">{{ article.heading | ltrim }}</h1>
<p class="created">
Posted at {{ article.date | strftime('%d.%m.%Y %H:%M:%S') }}
</p>
<p class="perex">
{{ article.perex | wordwrap(80) }}
</p>
Available functions
session, trans, var_dump, template_from_string, country_timezones
session
Function moves the functionality of the Laravel session()
helper function to Twig.
{{ session('my.session.key') }}
The example would output the value currently stored in my.session.key
.
See more about the Laravel session helper function here.
You can also use OctoberCMS function: {{ this.session.get('my.session.key') }}
, but it's little bit longer :-)
trans
Function moves the functionality of the Laravel trans()
helper function to Twig.
{{ trans('acme.blog::lang.app.name') }}
The example would output a value stored in a localization file of an imaginary blog plugin. See more about localization in Winter CMS here.
You can also use trans filter: {{ 'acme.blog::lang.app.name'|trans }}
.
var_dump
Dumps information about a variable. Can be also used as a filter.
<pre>{{ var_dump(users) }}</pre>
You can also use {{ dump(users) }} function to dump information about a variable. Properties are "clickable" to expand.
template_from_string
Function loads a template from a string.
{% set name = 'John' %}
{{ include(template_from_string("Hello {{ name }}")) }}
{{ include(template_from_string("Hurry up it is: {{ "now"|date("m/d/Y") }}")) }}
country_timezones
The country_timezones function returns the names of the timezones associated with a given country code:
{# Europe/Paris #} {{ country_timezones('FR')|join(', ') }}
Available filters
- PHP functions: strftime, ltrim, rtrim, var_dump, wordwrap
- custom functions: revision
- internationalized names filters: country_name, currency_name, currency_symbol, language_name, locale_name, timezone_name
- localized formatters filters: format_currency, format_number, format_*_number, format_datetime, format_date, format_time
strftime
Format a local time/date according to locale settings.
Posted at {{ article.date | strftime('%d.%m.%Y %H:%M:%S') }}
The example would output Posted at 04.01.2016 22:57:42. See more format parameters.
You can also use {{ carbon(article.date).formatLocalized('%d.%m.%Y %H:%M:%S') }}
.
ltrim
Strip whitespace (or other characters) from the beginning of a string.
Hello I'm {{ ' jack' | ltrim }}
The example would output Hello I'm jack without whitespaces from the start.
You can also use {{ ' I like Twig. '|trim(side='left') }}
native Twig filter.
rtrim
Strip whitespace (or other characters) from the end of a string.
Hello I'm {{ 'jack ' | rtrim }}
The example would output Hello I'm jack without whitespaces from the end.
You can also use {{ ' I like Twig. '|trim(side='right') }}
native Twig filter.
var_dump
Dumps information about a variable.
<pre>{{ users | var_dump }}</pre>
You can also use <pre>{{ var_dump(users) }}</pre>
or {{ dump(users) }}
functions.
wordwrap
Use the wordwrap filter to split your text into lines with equal length.
{{ "Lorem ipsum dolor sit amet, consectetur adipiscing" | wordwrap(10) }}
This example would print:
Lorem ipsu
m dolor si
t amet, co
nsectetur
adipiscing
The default separator is "\n", but you can easily change that by providing one:
{{ "Lorem ipsum dolor sit amet, consectetur adipiscing" | wordwrap(10, "zz\n") }}
This would result in:
Lorem ipsuzz
m dolor sizz
t amet, cozz
nsectetur zz
adipiscing
revision
Force the browser to reload cached modified/updated asset files. You can provide a format parameter so that the prepended timestamp gets converted accordingly to the PHP date() function.
usage
<img src="{{ 'assets/images/image_file.jpg' | theme | revision("m.d.y.H.i.s") }}" alt="an image" />
Will return something like
<img src="https://www.example.com/themes/my-theme/assets/image_file.png?12.03.16.04.52.38" alt="An image" />
See: vojtasvoboda#25
https://stackoverflow.com/questions/32414/how-can-i-force-clients-to-refresh-javascript-files
http://php.net/manual/en/function.date.php
country_name
The country_name filter returns the country name given its ISO-3166 two-letter code:
{# France #} {{ 'FR'|country_name }}
By default, the filter uses the current locale. You can pass it explicitly:
{# États-Unis #} {{ 'US'|country_name('fr') }}
currency_name
The currency_name filter returns the currency name given its three-letter code:
{# Euro #} {{ 'EUR'|currency_name }} {# Japanese Yen #} {{ 'JPY'|currency_name }}
By default, the filter uses the current locale. You can pass it explicitly:
{# yen japonais #} {{ 'JPY'|currency_name('fr_FR') }}
currency_symbol
The currency_symbol filter returns the currency symbol given its three-letter code:
{# € #} {{ 'EUR'|currency_symbol }} {# ¥ #} {{ 'JPY'|currency_symbol }}
By default, the filter uses the current locale. You can pass it explicitly:
{# ¥ #} {{ 'JPY'|currency_symbol('fr') }}
language_name
The language_name filter returns the language name given its two-letter code:
{# German #} {{ 'de'|language_name }}
By default, the filter uses the current locale. You can pass it explicitly:
{# allemand #} {{ 'de'|language_name('fr') }} {# français canadien #} {{ 'fr_CA'|language_name('fr_FR') }}
locale_name
The locale_name filter returns the locale name given its two-letter code:
{# German #} {{ 'de'|locale_name }}
By default, the filter uses the current locale. You can pass it explicitly:
{# allemand #} {{ 'de'|locale_name('fr') }} {# français (Canada) #} {{ 'fr_CA'|locale_name('fr_FR') }}
timezone_name
The timezone_name filter returns the timezone name given a timezone identifier:
{# Central European Time (Paris) #} {{ 'Europe/Paris'|timezone_name }} {# Pacific Time (Los Angeles) #} {{ 'America/Los_Angeles'|timezone_name }}
By default, the filter uses the current locale. You can pass it explicitly:
{# heure du Pacifique nord-américain (Los Angeles) #} {{ 'America/Los_Angeles'|timezone_name('fr') }}
format_currency
The format_currency filter formats a number as a currency:
{# €1,000,000.00 #} {{ '1000000'|format_currency('EUR') }}
You can pass attributes to tweak the output:
{# €12.34 #} {{ '12.345'|format_currency('EUR', {rounding_mode: 'floor'}) }} {# €1,000,000.0000 #} {{ '1000000'|format_currency('EUR', {fraction_digit: 4}) }}
The list of supported options:
- grouping_used;
- decimal_always_shown;
- max_integer_digit;
- min_integer_digit;
- integer_digit;
- max_fraction_digit;
- min_fraction_digit;
- fraction_digit;
- multiplier;
- grouping_size;
- rounding_mode;
- rounding_increment;
- format_width;
- padding_position;
- secondary_grouping_size;
- significant_digits_used;
- min_significant_digits_used;
- max_significant_digits_used;
- lenient_parse.
By default, the filter uses the current locale. You can pass it explicitly:
{# 1.000.000,00 € #} {{ '1000000'|format_currency('EUR', locale='de') }}
format_number and format_*_number
The format_number filter formats a number:
{{ '12.345'|format_number }}
You can pass attributes to tweak the output:
{# 12.34 #} {{ '12.345'|format_number({rounding_mode: 'floor'}) }} {# 1000000.0000 #} {{ '1000000'|format_number({fraction_digit: 4}) }}
The list of supported options:
- grouping_used;
- decimal_always_shown;
- max_integer_digit;
- min_integer_digit;
- integer_digit;
- max_fraction_digit;
- min_fraction_digit;
- fraction_digit;
- multiplier;
- grouping_size;
- rounding_mode;
- rounding_increment;
- format_width;
- padding_position;
- secondary_grouping_size;
- significant_digits_used;
- min_significant_digits_used;
- max_significant_digits_used;
- lenient_parse.
Besides plain numbers, the filter can also format numbers in various styles:
{# 1,234% #} {{ '12.345'|format_number(style='percent') }} {# twelve point three four five #} {{ '12.345'|format_number(style='spellout') }} {# 12 sec. #} {{ '12'|format_duration_number }}
The list of supported styles:
- decimal;
- currency;
- percent;
- scientific;
- spellout;
- ordinal;
- duration.
As a shortcut, you can use the format_*_number filters by replacing *
with a style:
{# 1,234% #} {{ '12.345'|format_percent_number }} {# twelve point three four five #} {{ '12.345'|format_spellout_number }}
You can pass attributes to tweak the output:
{# 12.3% #} {{ '0.12345'|format_percent_number({rounding_mode: 'floor', fraction_digit: 1}) }}
By default, the filter uses the current locale. You can pass it explicitly:
{# 12,345 #} {{ '12.345'|format_number(locale='fr') }}
format_datetime
The format_datetime filter formats a date time:
{# Aug 7, 2019, 11:39:12 PM #} {{ '2019-08-07 23:39:12'|format_datetime() }}
Format
You can tweak the output for the date part and the time part:
{# 23:39 #} {{ '2019-08-07 23:39:12'|format_datetime('none', 'short', locale='fr') }} {# 07/08/2019 #} {{ '2019-08-07 23:39:12'|format_datetime('short', 'none', locale='fr') }} {# mercredi 7 août 2019 23:39:12 UTC #} {{ '2019-08-07 23:39:12'|format_datetime('full', 'full', locale='fr') }}
Supported values are: none, short, medium, long, and full.
For greater flexibility, you can even define your own pattern (see the ICU user guide for supported patterns).
{# 11 oclock PM, GMT #} {{ '2019-08-07 23:39:12'|format_datetime(pattern="hh 'oclock' a, zzzz") }}
Locale
By default, the filter uses the current locale. You can pass it explicitly:
{# 7 août 2019 23:39:12 #} {{ '2019-08-07 23:39:12'|format_datetime(locale='fr') }}
Timezone
By default, the date is displayed by applying the default timezone (the one specified in php.ini or declared in Twig -- see below), but you can override it by explicitly specifying a timezone:
{{ datetime|format_datetime(locale='en', timezone='Pacific/Midway') }}
If the date is already a DateTime object, and if you want to keep its current timezone, pass false as the timezone value:
{{ datetime|format_datetime(locale='en', timezone=false) }}
The default timezone can also be set globally by calling setTimezone():
$twig = new \Twig\Environment($loader);
$twig->getExtension(\Twig\Extension\CoreExtension::class)->setTimezone('Europe/Paris');
format_date
The format_date filter formats a date. It behaves in the exact same way as the format_datetime filter, but without the time.
format_time
The format_time filter formats a time. It behaves in the exact same way as the format_datetime filter, but without the date.
For more info see UPGRADE.md guide.
Contributing
- Make template_from_string turned off by default and add special checkbox to the backend to allow it.
- Add missing unit tests.
- New filters ga and gtm for adding GA or GTM code (Heap Analytics) - {{ 'UA-1234567' | ga }}.
- Add cache extension.
Feel free to send pullrequest! Please, send Pull Request to master branch.
License
Twig extensions plugin is open-sourced software licensed under the MIT license same as OctoberCMS platform.