Mechanic filters
This page defines all of the Liquid filters that are available in Mechanic Liquid. Mechanic supports many of our own filters, as well as an array of filters drawn from Shopify Liquid.
Liquid filters should not be confused with event filters, which are used to conditionally ignore incoming events.
Data filters
browser
This filter converts a browser user agent string into an object that represents the browser itself. Data from Browserscope is used to match user agents.
{% assign browser = "Mozilla/5.0 (iPhone; CPU iPhone OS 12_4 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) GSA/79.0.259819395 Mobile/16G77 Safari/604.1" | browser %}
{{ browser }}
name: {{ browser.name }}
version: {{ browser.version }}
major version: {{ browser.version.major }}
minor version: {{ browser.version.minor }}
os: {{ browser.os }}
os name: {{ browser.os.name }}
os version: {{ browser.os.version }}
os major version: {{ browser.os.version.major }}
os minor version: {{ browser.os.version.minor }}
device: {{ browser.device }}
device name: {{ browser.device.name }}
device brand: {{ browser.device.brand }}
device model: {{ browser.device.model }}Google 79.0.259819395
name: Google
version: 79.0.259819395<br>major version: 79<br>minor version: 0
os: iOS 12.4<br>os name: iOS<br>os version: 12.4<br>os major version: 12<br>os minor version: 4
device: iPhone<br>device name: iPhone<br>device brand: Apple<br>device model: iPhonecsv, parse_csv
Supports converting a two-dimensional array to a CSV string, and back again.
Arguments
delimiter(optional): A single character that separates the fields in the CSV. Defaults to a comma.include_bom(optional): A boolean value that, when set to true, includes a Byte Order Mark (BOM) at the beginning of the CSV string to enhance compatibility with Microsoft Excel. Defaults to false.
date, parse_date
Mechanic's date filter is based on Shopify's date filter, and has several important extensions.
Format
Date formats may be given per Ruby's strftime. For an interactive format-building tool, see strfti.me.
Unlike Shopify Liquid, Mechanic's date filter does not require a format argument. If one is not given, Mechanic defaults to formatting the date per ISO8601.
Using the current time
This filter accepts the special value "now". This may optionally be combined with a single date calculation, as in "now + 5 days" or "now - 5 weeks". For specifics on date calculation, see notes below for the advance option.
Additional options
The date filter also accepts these following options, evaluated in the following order:
tzβ A timezone name from the TZ databaseIf given, the resulting time string will be in the specified timezone.
If this option is not provided, the time is assumed to be in the store's local timezone, as configured at the Shopify level.
All date calculations are performed with respect to the current timezone, with consideration for DST and other calendar variances.
beginning_of_year: trueorend_of_year: truebeginning_of_quarter: trueorend_of_quarter: truebeginning_of_month: trueorend_of_month: truebeginning_of_week: weekdayorend_of_month: weekdayweekdaymust be a string naming the first day of the week for the intended usage, e.g."sunday"or"monday"
beginning_of_day: trueormiddle_of_day: trueorend_of_day: trueadvance: "1 year 6 months"Supports any combination of years, months, weeks, days, hours, minutes, seconds
Supports positive and negative values
Durations are calculated in the order given, left to right
Seconds, minutes, and hours are all implemented as constant intervals
Days, weeks, months, and years are all variable-length, appropriate for the current time in the current timezone (see
tz). For example,{{ "2023-01-31" | date: "%F", advance: "1 year 1 month" }}returns2024-02-29.Commas and signs may be used for clarity. Pluralization is optional. All of the examples below are equivalent:
{{ "now" | date: advance: "-3 hours, +2 minutes, -1 second" }}{{ "now" | date: advance: "-3 hours, 2 minutes, -1 second" }}{{ "now" | date: advance: "-3 hour 2 minute -1 second" }}{{ "now" | date: advance: "-3 hours 2 minutes -1 seconds" }}
Parsing dates
Use parse_date to parse a date string, when its exact format is known. This filter is useful for strings that contain an ambiguous date value, like "01/01/01".
Under the hood, parse_date uses ActiveSupport::TimeZone#strptime, and inherits its behavior with regard to missing upper components.
This filter returns an ISO8601 string, representing the parsed date value in the store's local timezone. If the supplied date string cannot be parsed successfully, the filter will return nil.
gzip, gunzip
These filters allow you to compress and decompress strings, using gzip compression.
In general, all strings passing through Mechanic must be UTF-8, and must ultimately be valid when represented as JSON. However, because gzip'd content may not be UTF-8, and because it may be important to preserve the original encoding, the gunzip filter supports a force_utf8: false option. Use this when you're certain the original encoding must be preserved, if you ultimately intend to pass along the string in a JSON-friendly representation. (For example, you might gunzip a value, and then use the base64 filter to represent it safely within JSON.)
graphql_arguments
Useful for preparing key-value pairs of GraphQL query or mutation arguments.
This results in a GraphQL Shopify action containing the following GraphQL:
For a more complex example, see Set product or variant metafields values in bulk from the task library.
json, parse_json
Allows converting objects to their JSON representations, and parsing that JSON into hashes.
The parse_json filter raises an error when invalid JSON. To ignore parse errors, and to return null when an error is encountered, add silent: true to the filter's options:
jsonl, parse_jsonl
Allows for rendering an iterable object (i.e. an array) as a series of JSON lines, separated by simple newlines.
The parse_jsonl filter can be used to parse a series of JSON strings, each on their own line, into an array of hashes. Useful when preparing stub data for bulk operations.
The parse_jsonl filter raises an error when invalid JSONL is received.
parse_xml
Use this filter to parse an XML string. (Under the hood, this filter calls Hash::from_xml.) Useful for processing output from third-party APIs, either by responding to "http" actions, or by parsing content from inbound webhooks.
shopify
This filter accepts a GraphQL query string, sends it to Shopify, and returns the full response β including "data" and "errors".
GraphQL variables
This filter also supports GraphQL variables, via an optional named argument called variables.
Shopify Data filters
In addition to our own filters, Mechanic supports the following data filter from Shopify Liquid:
String filters
e164
This filter accepts a phone number β country code is required! β and outputs it in standard E.164 format. If the number does not appear valid, the filter returns nil.
match
Use this filter to match a string with a Ruby-compatible regular expression pattern (see Regexp).
This filter returns the entire matched string (i.e. MatchData#to_s). Use the "captures" or "named_captures" lookups to receive an array or hash of captures, respectively (i.e. MatchData#captures, MatchData#named_captures).
hmac_sha512
Works like hmac_sha256 from Shopify Liquid, but uses SHA-512 instead.
rsa_sha256, rsa_sha512
Accepts string input, given an RSA PEM key string as a filter option.
scan
Use this filter to find all available matches in a string, using a Ruby-compatible regular expression pattern (see Regexp).
This filter returns an array of matches, consisting of each matched string (i.e. MatchData#to_s). Use the "captures" or "named_captures" lookups on individual matches to receive an array or hash of captures, respectively (i.e. MatchData#captures, MatchData#named_captures).
sha512
Works like sha256 from Shopify Liquid, but uses SHA-512 instead.
unindent
Use this filter on strings to remove indentation from strings.
Shopify String filters
In addition to our own filters, Mechanic supports the following string filters from Shopify Liquid:
Math filters
currency
Formats a number (given as an integer, float, or string) as currency. Called with no arguments, this filter uses the store's primary currency and default locale.
A three-character ISO currency code may be specified as the first argument; currency support is drawn from the money project. The locale may be overridden as a named option; locale support is drawn from rails-i18n.
Note that this filter does not automatically append the currency ISO code (e.g. it will not generate output resembling "β¬100,000.00 EUR"). To add the ISO code manually, use one of these examples:
Shopify Math filters
In addition to our own filters, Mechanic supports the following math filters from Shopify Liquid:
Array filters
in_groups
This filter is an implementation of Array#in_groups. It accepts an array, and an integer count, and β optionally β a "fill_with" option.
in_groups_of
This filter is an implementation of Array#in_groups_of. It accepts an array, and an integer count, and β optionally β a "fill_with" option.
This filter is particularly useful when performing work in batches, by making it easy to split an array of potentially large size into smaller pieces of controlled size.
index_by
This filter accepts the name of an object property or attribute, and returns a hash that whose values are every element in the array, keyed by every element's corresponding property or attribute.
push
This filter appends any number of arguments onto the provided array, returning a new array, leaving the original unmodified.
sample
This filter can be used on any array. Used without any arguments, it returns a single random element from the array. Provide an integer argument to return another array of that size, containing a random subset of the input array.
slice
When applied to an array, this filter accepts an integer offset, and an optional integer length (defaulting to 1). If the length is 1, it returns the single element found at that index of the input array. Otherwise, it returns a slice of the array, beginning at the provided index, having the provided length.
Negative offsets begin counting from the end of the array.
sort_naturally
Sorts an array uses the human-friendly sort order defined by naturally. Accepts a single optional parameter, specifying an attribute to sort.
sum
Returns the sum of all elements in an array.
Note that Mechanic's implementation of this filter predates Shopify's sum filter, and so there are two notable differences:
In Mechanic, the
sumfilter requires that every element of the array be a number.In Mechanic, the sum filter cannot operate on an array of objects. To achieve similar behavior to Shopify, you can combine
sumwith themapfilter:
unshift
This filter prepends any number of arguments onto the provided array, returning a new array, leaving the original unmodified.
Shopify Array filters
In addition to our own filters, Mechanic supports the following array filters from Shopify Liquid:
Hash filters
compact
When applied to a hash, this filter returns a new hash which omits all keys having nil values.
Note that the filter only operates on the top-level keys, it does not affect keys in lower levels of a nested hash. If you need to omit nil keys from a nested hash, you must apply the compact filter to the nested hash directly.
except
This filter accepts one or more string arguments, corresponding to keys that should be left out of the output. The filter returns a new hash, containing all the key/value pairs of the original hash except those keys named as arguments.
keys
Returns an array of keys found in the supplied hash.
slice
When applied to a hash, the slice filter accepts one or more string arguments, corresponding to keys that the hash may contain. This filter will then return a new hash, containing only matching key/value pairs from the original hash.
values
Returns an array of values found in the supplied hash.
Last updated
Was this helpful?