GuideWriting templates

Optional and Fluid-specific filters

Filters that are specific to Fluid, and the opt-in color and money filters.

Fluid-specific filtersLink to this heading

Some non-standard filters are provided by default:

format_dateLink to this heading

Formats dates and times using standard .NET date and time formats. It uses the culture of the template context, or the one named by an optional second argument, as in format_date: "D", "de-DE". An unknown culture name uses the culture of the template context.

Input

"now" | format_date: "G"

Output

6/15/2009 1:45:30 PM

Documentation: https://docs.microsoft.com/en-us/dotnet/standard/base-types/standard-date-and-time-format-strings

format_numberLink to this heading

Formats numbers using standard .NET number formats. Like format_date, it takes an optional culture name as its second argument, as in format_number: "N2", "de-DE".

Input

123 | format_number: "N"

Output

123.00

Documentation: https://docs.microsoft.com/en-us/dotnet/standard/base-types/standard-numeric-format-strings

format_stringLink to this heading

Formats custom strings using standard .NET format strings. A culture named argument sets the culture like the second argument of format_date, as in format_string: 123, culture: "de-DE".

Input

"hello {0} {1:C}" | format_string: "world" 123

Output

hello world $123.00

Documentation: https://docs.microsoft.com/en-us/dotnet/api/system.string.format

Color filtersLink to this heading

Color filters are opt-in. Register them with TemplateOptionsBuilder.WithColorFilters():

var options = new TemplateOptionsBuilder()
    .WithColorFilters()
    .Build();

The filters accept three- and six-digit hexadecimal colors and rgb/rgba and hsl/hsla functions with the existing comma-delimited syntax and optional alpha:

Component Supported input
RGB channels Numbers (including fractions such as 10.1) or percentages; all three channels must use the same type
Hue Degrees without a unit, or an angle in deg, rad, grad, or turn
Saturation and lightness Percentages
Alpha A number or percentage, including leading-dot numbers such as .4

Numbers use invariant decimal-point syntax and can use signs and exponent notation. RGB channels, saturation, lightness, and alpha are clamped to their valid ranges. Hue wraps around a full revolution. RGB channels are stored as integers: percentages map 100% to 255, and fractional channel values round to the nearest integer, with half-way values rounded upward. Output formatting is unchanged; RGB/HSL alpha is rounded to one decimal place, while color_extract: 'alpha' returns the parsed alpha without that output rounding. Conversion to hex omits alpha.

Source Result
{{ 'rgb(10%, 10%, 20%, 40%)' \| color_to_hex }} #1a1a33
{{ 'hsla(.25turn, 100%, 50%, 50%)' \| color_to_rgb }} rgba(128, 255, 0, 0.5)
{{ 'rgb(10.1, 11.2, 11.3, .4)' \| color_extract: 'alpha' }} 0.4

Malformed or non-finite components produce an empty filter result. This is not a complete CSS color parser: modern space-separated/slash-alpha syntax, named colors, other color spaces, and CSS expressions are not supported.

Money filtersLink to this heading

Fluid implements the Shopify money filters. They are not registered by default, register them with TemplateOptionsBuilder.WithMoneyFilters().

var options = new TemplateOptionsBuilder()
    .WithMoneyFilters()
    .Build();
Filter Source Result
money {{ 1134.65 \| money }} $1,134.65
money_with_currency {{ 1134.65 \| money_with_currency }} $1,134.65 USD
money_without_currency {{ 1134.65 \| money_without_currency }} 1,134.65
money_without_trailing_zeros {{ 10.00 \| money_without_trailing_zeros }} $10

Amounts are rounded away from zero, so 10.005 is rendered as $10.01.

Cultures and currenciesLink to this heading

By default, the currency and the way amounts are formatted are derived from TemplateOptions.CultureInfo, which is set with TemplateOptionsBuilder.WithCultureInfo(). The default culture is the invariant one, which has no currency, in which case USD is used.

var options = new TemplateOptionsBuilder()
    .WithMoneyFilters()
    .WithCultureInfo(new CultureInfo("de-DE"))
    .Build();
{{ 1134.65 | money_with_currency }}
1.134,65 € EUR

A specific currency can be set with MoneyOptions.Currency, using its ISO 4217 code. It is also accepted as an argument of every money filter, which is useful when a single template renders multiple currencies.

var options = new TemplateOptionsBuilder()
    .WithMoneyFilters()
    .WithMoneyOptions(new MoneyOptions { Currency = "EUR" })
    .Build();
{{ 10 | money }}
{{ 10 | money: 'GBP' }}
{{ 10 | money: currency: 'JPY' }}
€10.00
£10.00
¥10

The symbol and the number of decimal digits of the most common currencies are known to Fluid. Others can be added, or replaced, with MoneyOptions.WithCurrency(), which returns a new instance. A currency that is not registered is rendered using its code as the symbol.

var moneyOptions = new MoneyOptions()
    .WithCurrency(new MoneyCurrency("BTC", "₿", decimalDigits: 8));

var options = new TemplateOptionsBuilder()
    .WithMoneyFilters()
    .WithMoneyOptions(moneyOptions)
    .Build();

Amounts stored in centsLink to this heading

Shopify stores prices as integers representing cents. Set MoneyOptions.AmountsInCents to divide the input of the money filters by 100, which makes it possible to reuse Shopify templates as-is.

var options = new TemplateOptionsBuilder()
    .WithMoneyFilters()
    .WithMoneyOptions(new MoneyOptions { AmountsInCents = true })
    .Build();
{{ 1450 | money }}
$14.50

Custom formatsLink to this heading

MoneyOptions.MoneyFormat and MoneyOptions.MoneyWithCurrencyFormat override the culture based formatting, using the same placeholders as the Shopify currency formatting settings. These placeholders are culture independent.

Placeholder Result for 1134.65
{{amount}} 1,134.65
{{amount_no_decimals}} 1,135
{{amount_with_comma_separator}} 1.134,65
{{amount_no_decimals_with_comma_separator}} 1.135
{{amount_with_apostrophe_separator}} 1'134.65
{{amount_no_decimals_with_space_separator}} 1 135
{{amount_with_space_separator}} 1 134,65
{{amount_with_period_and_space_separator}} 1 134.65
{{currency}} the ISO 4217 code of the currency, e.g. USD
{{currency_symbol}} the symbol of the currency, e.g. $

{{currency}} and {{currency_symbol}} are specific to Fluid, and let a single format be used with the currency that is resolved when the template is rendered. Unknown placeholders are rendered verbatim.

var options = new TemplateOptionsBuilder()
    .WithMoneyFilters()
    .WithMoneyOptions(new MoneyOptions { MoneyFormat = "{{amount_with_comma_separator}} kr" })
    .Build();
{{ 1134.65 | money }}
1.134,65 kr

money_without_currency always renders the amount on its own and ignores these formats. When MoneyWithCurrencyFormat is not set, money_with_currency uses MoneyFormat followed by the currency code.

Rendering a different currency per requestLink to this heading

MoneyOptions is immutable application-wide configuration, set with TemplateOptionsBuilder.WithMoneyOptions(). To use a different currency for a single rendering, assign a MoneyOptions instance on the TemplateContext.

var context = new TemplateContext(options)
{
    MoneyOptions = new MoneyOptions { Currency = "EUR" }
};

Esc to close