Twig extensions
, (*1)
Twig extensions plugin for OctoberCMS adds new filter and functions to your templates. No other plugin dependencies. Tested with the latest stable OctoberCMS 3.1.18 on PHP 8.0., (*2)
Versions
There are two versions of this plugin - 1.x and 2.x. For older October 1.0.x, 1.1.x or 2.x.x use special branch 1.x. For October 3.1+ use master branch.
For old Laravel 5.4 October's versions use special branch laravel54., (*3)
For migrating between plugin's version 1 and version 2 you can use special UPGRADE.md guide., (*4)
Installation
Install plugin from CMS backend or by Composer:, (*5)
composer require vojtasvoboda/oc-twigextensions-plugin
Than you can use newly added filters/functions at your templates:, (*6)
<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, (*7)
session
Function moves the functionality of the Laravel session() helper function to Twig., (*8)
{{ 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., (*9)
You can also use OctoberCMS function: {{ this.session.get('my.session.key') }}, but it's little bit longer :-), (*10)
trans
Function moves the functionality of the Laravel trans() helper function to Twig., (*11)
{{ 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 October CMS here., (*12)
You can also use trans filter: {{ 'acme.blog::lang.app.name'|trans }}., (*13)
var_dump
Dumps information about a variable. Can be also used as a filter., (*14)
<pre>{{ var_dump(users) }}</pre>
You can also use {{ dump(users) }} function to dump information about a variable. Properties are "clickable" to expand., (*15)
template_from_string
Function loads a template from a string., (*16)
{% 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:, (*17)
{# 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., (*18)
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., (*19)
You can also use {{ carbon(article.date).formatLocalized('%d.%m.%Y %H:%M:%S') }}., (*20)
ltrim
Strip whitespace (or other characters) from the beginning of a string., (*21)
Hello I'm {{ ' jack' | ltrim }}
The example would output Hello I'm jack without whitespaces from the start., (*22)
You can also use {{ ' I like Twig. '|trim(side='left') }} native Twig filter., (*23)
rtrim
Strip whitespace (or other characters) from the end of a string., (*24)
Hello I'm {{ 'jack ' | rtrim }}
The example would output Hello I'm jack without whitespaces from the end., (*25)
You can also use {{ ' I like Twig. '|trim(side='right') }} native Twig filter., (*26)
var_dump
Dumps information about a variable., (*27)
<pre>{{ users | var_dump }}</pre>
You can also use <pre>{{ var_dump(users) }}</pre> or {{ dump(users) }} functions., (*28)
wordwrap
Use the wordwrap filter to split your text into lines with equal length., (*29)
{{ "Lorem ipsum dolor sit amet, consectetur adipiscing" | wordwrap(10) }}
This example would print:, (*30)
Lorem ipsu
m dolor si
t amet, co
nsectetur
adipiscing
The default separator is "\n", but you can easily change that by providing one:, (*31)
{{ "Lorem ipsum dolor sit amet, consectetur adipiscing" | wordwrap(10, "zz\n") }}
This would result in:, (*32)
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., (*33)
usage
<img src="{{ 'assets/images/image_file.jpg' | theme | revision("m.d.y.H.i.s") }}" alt="an image" />
Will return something like, (*34)
<img src="https://www.example.com/themes/my-theme/assets/image_file.png?12.03.16.04.52.38" alt="An image" />
See: https://github.com/vojtasvoboda/oc-twigextensions-plugin/issues/25, (*35)
https://stackoverflow.com/questions/32414/how-can-i-force-clients-to-refresh-javascript-files, (*36)
http://php.net/manual/en/function.date.php, (*37)
country_name
The country_name filter returns the country name given its ISO-3166 two-letter code:, (*38)
{# France #}
{{ 'FR'|country_name }}
By default, the filter uses the current locale. You can pass it explicitly:, (*39)
{# États-Unis #}
{{ 'US'|country_name('fr') }}
currency_name
The currency_name filter returns the currency name given its three-letter code:, (*40)
{# Euro #}
{{ 'EUR'|currency_name }}
{# Japanese Yen #}
{{ 'JPY'|currency_name }}
By default, the filter uses the current locale. You can pass it explicitly:, (*41)
{# yen japonais #}
{{ 'JPY'|currency_name('fr_FR') }}
currency_symbol
The currency_symbol filter returns the currency symbol given its three-letter code:, (*42)
{# € #}
{{ 'EUR'|currency_symbol }}
{# ¥ #}
{{ 'JPY'|currency_symbol }}
By default, the filter uses the current locale. You can pass it explicitly:, (*43)
{# ¥ #}
{{ 'JPY'|currency_symbol('fr') }}
language_name
The language_name filter returns the language name given its two-letter code:, (*44)
{# German #}
{{ 'de'|language_name }}
By default, the filter uses the current locale. You can pass it explicitly:, (*45)
{# 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:, (*46)
{# German #}
{{ 'de'|locale_name }}
By default, the filter uses the current locale. You can pass it explicitly:, (*47)
{# 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:, (*48)
{# 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:, (*49)
{# heure du Pacifique nord-américain (Los Angeles) #}
{{ 'America/Los_Angeles'|timezone_name('fr') }}
The format_currency filter formats a number as a currency:, (*50)
{# €1,000,000.00 #}
{{ '1000000'|format_currency('EUR') }}
You can pass attributes to tweak the output:, (*51)
{# €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:, (*52)
- 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:, (*53)
{# 1.000.000,00 € #}
{{ '1000000'|format_currency('EUR', locale='de') }}
The format_number filter formats a number:, (*54)
{{ '12.345'|format_number }}
You can pass attributes to tweak the output:, (*55)
{# 12.34 #}
{{ '12.345'|format_number({rounding_mode: 'floor'}) }}
{# 1000000.0000 #}
{{ '1000000'|format_number({fraction_digit: 4}) }}
The list of supported options:, (*56)
- 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:, (*57)
{# 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:, (*58)
- decimal;
- currency;
- percent;
- scientific;
- spellout;
- ordinal;
- duration.
As a shortcut, you can use the format_*_number filters by replacing * with a style:, (*59)
{# 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:, (*60)
{# 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:, (*61)
{# 12,345 #}
{{ '12.345'|format_number(locale='fr') }}
The format_datetime filter formats a date time:, (*62)
{# Aug 7, 2019, 11:39:12 PM #}
{{ '2019-08-07 23:39:12'|format_datetime() }}
You can tweak the output for the date part and the time part:, (*63)
{# 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., (*64)
For greater flexibility, you can even define your own pattern (see the ICU user guide for supported patterns)., (*65)
{# 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:, (*66)
{# 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:, (*67)
{{ 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:, (*68)
{{ datetime|format_datetime(locale='en', timezone=false) }}
The default timezone can also be set globally by calling setTimezone():, (*69)
$twig = new \Twig\Environment($loader);
$twig->getExtension(\Twig\Extension\CoreExtension::class)->setTimezone('Europe/Paris');
The format_date filter formats a date. It behaves in the exact same way as the format_datetime filter, but without the time., (*70)
The format_time filter formats a time. It behaves in the exact same way as the format_datetime filter, but without the date., (*71)
Removed functions
Functions used in plugin's version 1.x for October 1.0.x, 1.1.x, 2.0.x and removed from this version:, (*72)
- config() - it's native function since October 3.1.17
- env() - it's native function since October 3.1.17
Removed filters
Filters used in plugin's version 1.x for October 1.0.x, 1.1.x, 2.0.x and removed from this version:, (*73)
- uppercase - use str_upper or just upper
- lowercase - use str_lower or just lower
- ucfirst - use str_ucfirst
- lcfirst - use str_lcfirst
- str_repeat - it's native filter now
- plural - use str_plural
- truncate - use str_limit
- strpad - use str_pad_both
- str_replace - it's native filter now
- strip_tags - use html_strip
- leftpad - use str_pad_left
- rightpad - use str_pad_right
- rtl - use str_reverse
- shuffle - use
collect(songs).shuffle()
- time_diff - use
carbon(post.published_at).diffForHumans()
- localizeddate - use format_date
- localizednumber - use format_number
- localizedcurrency - use format_currency
- mailto - use html_mailto
- var_dump - use dump function
- sortbyfield - use
collect(data).sortBy('age') or collect(data).sortByDesc('age')
For more info see UPGRADE.md guide., (*74)
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., (*75)
License
Twig extensions plugin is open-sourced software licensed under the MIT license same as OctoberCMS platform., (*76)
Wallogit.com
