Arrays and collections
Use these filters to create, combine, search, group and reshape collections. In repeating groups, work with the arrays stored under each inner field ID; the group itself is not a Liquid value.
Standard Liquid filters
These filters are provided as standard by the Liquid language. They are available anywhere Govforms accepts a Liquid template.
| Filter | What it does | Example |
|---|---|---|
array_to_sentence_string(connector) | Joins array items as a sentence Separates items with commas and uses the connector before the final item. | {{ names | array_to_sentence_string: "and" }} → Alex, Sam, and Jo |
compact() | Removes nil values from array Filters out null and undefined values. | {{ array | compact }} → removes nil values |
concat(array) | Concatenates arrays Combines input array with another array. | {{ arr1 | concat: arr2 }} → combined array |
find(property, expected) | Finds the first matching array item Returns the first object whose property equals the expected value. If expected is omitted, the property must be truthy. | {{ users | find: "name", "Sam" | json }} |
find_exp(item_name, expression) | Finds the first array item matching an expression Evaluates a Liquid expression for each item and returns the first match. | {{ users | find_exp: "user", "user.age >= 18" | json }} |
find_index(property, expected) | Finds the index of the first matching array item Returns the zero-based index of the first object whose property matches. | {{ users | find_index: "name", "Sam" }} |
find_index_exp(item_name, expression) | Finds the index of the first item matching an expression Evaluates a Liquid expression for each item and returns the first matching zero-based index. | {{ users | find_index_exp: "user", "user.age >= 18" }} |
first() | Gets first element of array Returns first item in array or first character of string. | {{ "hello" | first }} → h |
group_by(property) | Groups array items by a property Returns groups with name and items properties for each distinct property value. | {{ users | group_by: "team" | json }} |
group_by_exp(item_name, expression) | Groups array items using an expression Evaluates a Liquid expression for each item and groups items by the result. | {{ users | group_by_exp: "user", "user.age >= 18" | json }} |
has(property, expected) | Checks whether an array contains a matching item Returns true when an object property matches the expected value. | {{ users | has: "name", "Sam" }} → true |
has_exp(item_name, expression) | Checks whether any array item matches an expression Returns true when the Liquid expression is true for at least one item. | {{ users | has_exp: "user", "user.age >= 18" }} → true |
join(separator) | Joins array elements with separator Concatenates array items with specified separator. | {{ "a,b,c" | split: "," | join: " - " }} → a - b - c |
last() | Gets last element of array Returns last item in array or last character of string. | {{ "hello" | last }} → o |
map(property) | Extracts property from array of objects Creates array of property values from object array. | {{ users | map: "name" }} → array of name values |
pop() | Removes the last array item Returns a copy of the array without its final item. | {{ values | pop | json }} |
push(item) | Adds an item to the end of an array Returns a copy of the array with the supplied item appended. | {{ values | push: new_value | json }} |
reject(property, expected) | Rejects matching array items Returns objects whose property does not equal the expected value. If expected is omitted, rejects truthy properties. | {{ users | reject: "inactive", true | json }} |
reject_exp(item_name, expression) | Rejects array items matching an expression Returns items for which the Liquid expression evaluates to false. | {{ users | reject_exp: "user", "user.inactive" | json }} |
reverse() | Reverses array or string Returns array/string with elements in reverse order. | {{ "hello" | reverse }} → olleh |
sample(count) | Selects random array items or characters Returns one random item by default, or an array containing the requested number of random items. | {{ values | sample }} |
shift() | Removes the first array item Returns a copy of the array without its first item. | {{ values | shift | json }} |
size() | Returns size of array or string Gets length/count of elements. | {{ "hello" | size }} → 5 |
slice(start, length) | Extracts substring or subarray Returns portion starting at index for specified length. | {{ "hello" | slice: 1, 3 }} → ell |
sort(property) | Sorts array Sorts array elements, optionally by property name. | {{ "b,a,c" | split: "," | sort | join: "," }} → a,b,c |
sort_natural(property) | Sorts array using natural ordering Sorts with natural number ordering (10 after 2). | {{ "item10,item2,item1" | split: "," | sort_natural | join: "," }} → item1,item2,item10 |
sum(property) | Adds array values Returns the total of numeric array values, optionally reading a property from each object. | {{ order_items | sum: "price" }} |
uniq() | Removes duplicate values from array Returns array with unique elements only. | {{ [1,2,2,3] | uniq }} → [1,2,3] |
unshift(item) | Adds an item to the start of an array Returns a copy of the array with the supplied item prepended. | {{ values | unshift: new_value | json }} |
where(property, expected) | Selects matching array items Returns objects whose property equals the expected value. If expected is omitted, the property must be truthy. | {{ users | where: "active", true | json }} |
where_exp(item_name, expression) | Selects array items matching an expression Returns items for which the Liquid expression evaluates to true. | {{ users | where_exp: "user", "user.age >= 18" | json }} |
Govforms filters
These filters are added by Govforms for service-building and data-handling tasks.
| Filter | What it does | Example |
|---|---|---|
array(...items) | Creates array from arguments Constructs array from provided values. | {{ "item1" | array: "item2", "item3" }} |
clone(object) | Creates deep copy of object Returns structurally cloned copy of the object. | {{ original_object | clone }} |
delete(object, key) | Removes property from object Deletes the specified key from the object. | {{ my_object | delete: "unwanted_key" }} |
equals_or_includes(value, item) | Checks equality or array inclusion Returns true if value equals item, or if value is array containing item. | {{ field_value | equals_or_includes: "target" }} |
includes_item(array, item) | Checks if array contains specific item Returns true if the item is found in the array. | {{ my_array | includes_item: "search_value" }} |
is_array(value) | Checks if value is an array Returns true if value is an array object. | {{ my_value | is_array }} |
num_items(object) | Returns number of properties in object Counts the number of keys in an object. | {{ my_object | num_items }} |
object_keys(object) | Returns array of object property names Gets all enumerable property names from the object. | {{ my_object | object_keys }} |
object_values(object) | Returns array of object property values Gets all enumerable property values from the object. | {{ my_object | object_values }} |
remove_empty_arrays(object) | Removes empty arrays from objects recursively Cleans objects by removing properties whose value is an empty array. | {{ form_data | remove_empty_arrays }} |
remove_empty_objects(object) | Removes empty objects from objects recursively Cleans objects by removing properties whose value is an object with no properties. | {{ form_data | remove_empty_objects }} |
remove_empty_properties(object) | Removes empty properties from objects recursively Cleans objects by removing null, undefined, empty strings, and empty arrays/objects. | {{ my_object | remove_empty_properties }} |
remove_internal_properties(object) | Removes internal properties from objects recursively Cleans objects by removing properties whose name starts with an underscore. | {{ form_data | remove_internal_properties }} |
remove_null_properties(object) | Removes null properties from objects recursively Cleans objects by removing properties whose value is null. | {{ form_data | remove_null_properties }} |
remove_properties_from_object(object, ...keys) | Removes specific properties by key from objects recursively Removes all properties matching the specified keys throughout the object tree. | {{ my_object | remove_properties_from_object: "password", "token" }} |
set(object, key, value) | Sets property on object Assigns value to the specified key on the object. | {{ my_object | set: "new_key", "new_value" }} |
with_attribute(html_string, attribute_name, attribute_value) | Adds HTML attribute to element Takes an HTML element string and adds the specified attribute with value. Useful for adding ARIA attributes, data attributes, or other HTML attributes to dynamically generated elements. The attribute value is automatically escaped to prevent XSS. | {{ '<button type="button">Click</button>' | with_attribute: "aria-label", "Submit form" }} |