README

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.

Versions

October 1.0.x, 1.1.x or 2.x.x - use special branch 1.x October 3.1+ or 4.x - use master branch For old Laravel 5.4 October's versions - use special branch laravel54

For migrating between plugin's version 1 and version 2 you can use special UPGRADE.md guide.

Installation

Install plugin from CMS backend or by Composer:

composer require vojtasvoboda/oc-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 October 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: #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.

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:

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:

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.

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.

vojtasvoboda / twigextensions-plugin

Maintainers

Details

README

Versions

Installation

Available functions

session

trans

var_dump

template_from_string

country_timezones

Available filters

strftime

ltrim

rtrim

var_dump

wordwrap

revision

usage

country_name

currency_name

currency_symbol

language_name

locale_name

timezone_name

format_currency

format_number and format_*_number

format_datetime

Format

Locale

Timezone

format_date

format_time

Removed functions

Removed filters

Contributing

License