String Filters

These are provided in the default filters. Specifically, when TemplateOptions is constructed, these are added via the extension method WithStringFilters.

Contents

    append

    Adds the first argument to end of the input string.

    {% assign name = "Deane" %}
    My full name is {{ name | append:" Barker" }}.
    My name is Deane Barker.

    Clearly, given that Fluid is a templating language itself, there’s some questionable utility here. A template is fundamentally a way to glue text together. Put another way, you could just as easily do this:

    My full name is {{ name }} Barker.

    You would probably use this only when you needed to feed the results into another filter.

    capitalize

    Capitalizes the first character in a string, and every character that follows whitespace. If your value isn’t a StringValue, it will get turned into one.

    {% assign name = "deane barker" %}
    My name is {{ name | capitalize }}.
    My name is Deane Barker.

    Notably, this filter does not use any of the System.Globalization functionality, like TextInto.ToTitleCase(), so don’t be surprised if it acts differently. It literally iterates the characters in the string, detects the beginning of the string or any whitespace, then capitalizes the next character.

    downcase

    Turns a string into lower-case. Simply calls ToLower() on whatever ToStringValue() returns (so if it’s not a StringValue it will get turned into one.)

    {% assign name = "Deane Barker" %}
    My informal name is {{ name | downcase }}.
    My information name is deane barker.

    lstrip

    Strips whitespace from the start of a string. Internally, it calls TrimStart() on whatever ToStringValue() returns. (No example because whitespace is vague to demonstrate.)

    rstrip

    Strips whitespace from the end of a string. Internally, it calls TrimEnd() on whatever ToStringValue() returns. (No example because whitespace is vague to demonstrate.)

    newline_to_br

    Replaces newlines – both \r\n and \n – with <br /> tags.

    context.SetValue("body", @"This is my first sentence.
    
    This is my second");
    {{ body | newline_to_br }}
    This is my first sentence.<br /><br />This is my second.

    prepend

    Works the same as append but adds the input string to the end of the first argument.

    replace

    StringFilters.Replace

    Replaces one string with another, within the input string. This filter simply wraps Replace. It takes two arguments:

    1. The old string. This is required.
    2. The new string. This is optional. If not provided, it defaults to an empty string, which essentially removes the old string.
    {{ "Deane" | replace:"e","x" }}
    {{ "Deane" | replace:"e" }}
    Dxanx
    Dan

    replace_first

    StringFilters.ReplaceFirst

    Functions the same as replace, but stops after the first replacement.

    remove

    Removes a strings from the input string. Functions the same as replace without a second argument (see second example, above).

    remove_first

    Functions the same as remove but stops after the first removal.

    slice

    Extracts a range of one or more elements from an array or string. Takes two arguments:

    1. The starting index. This is required, and must be an integer.
    2. The desired length. This is optional. If not provided, it defaults to 1.

    Internally, it has different code for arrays and strings, but the easiest way to think about it is to remember that a string is just an array of characters.

    {{ "Alec,Gabrielle,Isabella" | split:"," | slice:1  }}
    {{ "Deane" | slice:1 }}
    Gabrielle
    e

    In the above example, we’re starting at index 1 (the second element) and requesting one item. If we provided a second argument, we can get more than one item.

    {{ "Alec,Gabrielle,Isabella" | split:"," | slice:1,2  }}
    {{ "Deane" | slice:1,2 }}
    GabrielleIsabella
    ea

    You can also use negative numbers for the starting index, which will count back from the end.

    {{ "Deane" | slice:-3,2 }}
    an

    A starting index of -1 with no length is an easy way to get the last element, however it’s no different than using the .last member.

    split

    Splits a string on a supplied delimiter. If a delimiter isn’t provided, splits the string into an array of characters. Either way, it returns an ArrayValue of StringValues.

    {{ "My name is Deane Barker" | split:" " | join:", " }}
    My, name, is, Deane, Barker

    Note that this is presently the only way to form an array directly in Liquid.

    strip

    Trims whitespace from both ends of a string. Internally, it calls Trim() on whatever ToStringValue() returns. (No example because whitespace is vague to demonstrate.)

    strip_newlines

    Replaces any newlines or carriage returns with empty strings.

    {% assign phrase = "My name is 
    Deane Barker" %}
    {{ phrase | strip_newlines}}
    My name is Deane Barker

    Clearly, the example is a little contrived because you could also solve this by just not having the assign statement wrap lines. Also, note that this doesn’t replace the newlines with spaces, so if there’s no whitespace at the end of the first line, you’ll get this:

    My name isDeane Barker

    truncate

    Returns the first X characters, appended with a suffix. It takes two optional arguments:

    1. The number of characters to reveal. If this is not supplied (or is non-numeric) it will default to 50.
    2. The suffix. If this is not supplied, it will default to an ellipsis ()

    The character count is reduced by the length of the suffix. So, if you truncate to 10 using the default suffix, you will get 7 characters plus the 3 dots.

    {% assign name = "Deane Barker" %}
    {{ name | truncate:10 }}
    Deane B...

    (This can cause some weirdness if you’re then processing with Markdown, since three consecutive dots will often get replaced by a single character code, leaving your character counts off by two.)

    You can pass in your own suffix, including an empty string. If you pass in an empty string, your character count will be accurate and exact.

    {{ name | truncate:3,"" }}
    Dea

    Any number value equal to or longer than the input string will result in the entire string being returned, regardless of suffix. This can lead to a sudden drop in revealed characters when using a suffix, because reducing the character count by one less than the length of the string causes the suffix length to be taken into account.

    {{ name | truncate:12 }}
    {{ name | truncate:11 }}
    Deane Barker
    Deane Ba...

    truncatewords

    Returns the first X words, appended by a suffix. It takes two arguments:

    1. The number of words to reveal. This defaults to 0, which means nothing will be returned if the argument is not provided. (Amusingly, the suffix will still be appended.)
    2. The suffix to append. This defaults to an ellipsis ().

    The filter calculates “words” by simply counting whitespace. Every time it crosses over whitespace, it increments the word count by 1.

    {% assign phrase = "My name is Deane Barker" %}
    {{ phrase | truncatewords:3 }}
    My name is...

    upcase

    Turns a string into upper case. See notes for downcase above.

    This is item #5 in a sequence of 5 items.

    You can use your left/right arrow keys or swipe left/right to navigate