Skip to content
Log in

New - Liquid Tag Reference

On this page

The new tag creates a value and assigns it to a variable: an empty or JSON-seeded List or Map, a UUID, or a random number. Use it to start a collection that you then build up with filters.

Syntax

```liquid

{% new %} {% new = %} {% new Rand min: , max: %} ```

Property Value
Tag Name new
Type Simple tag
Source Hydrofoil (core)

Types

Type Creates Seed or options Available in POS
List A list Optional JSON array string, such as '["a","b"]' Yes
Map A map of keys to values Optional JSON object string, such as '{"mode":"grid"}' Yes
UUID A random version 4 UUID string None No
Rand A random number between min and max, inclusive min (default 0) and max (default 100) No

The type name is case-sensitive. Any other type name stops the template with Liquid syntax error (line N): unknown object type <name>.

Empty and seeded lists and maps

Leave off the = and the value to create an empty List or Map. This is the usual way to start a collection:

```liquid

{%- new List codes -%} {%- new Map labels -%} ```

To start with values, pass a JSON string after =. The value is parsed as JSON each time the tag renders:

```liquid

{%- new List codes = ‘[“red”,”green”]’ -%} {%- new Map settings = ‘{“mode”:”grid”,”columns”:3}’ -%} {{ settings.mode }} ```

On the web storefront, the seed must be a JSON string. Each of these gives an empty List or Map instead, with no error on the page:

  • An empty string, such as {% new Map settings = '' %}.
  • Text that is not valid JSON. A typo in the seed therefore looks like missing data.
  • A value that is not a string, such as the list from {% new List parts = 'a,b' | split: ',' %}. To keep a list you already have, assign it instead.

:::note POS views differ on the last point: on the POS, a seed that is already a List or Map is copied into the new variable rather than discarded. :::

Inside loops

The tag creates a fresh List or Map every time it renders. Placed inside a {% for %} loop, it resets the variable on each pass, which suits a per-item collection. To collect values across every pass, create the List or Map before the loop.

Building up a list or map

Add to a Map with the set_key filter and to a List with the push filter. Assign the result back to the variable. A Map read from the variable is a fresh copy each time, so a set_key that is not assigned back is lost.

```liquid

{%- new Map names_by_code -%} {%- for product in content_block.products -%} {%- assign names_by_code = names_by_code | set_key: product.product_code, product.name -%} {%- endfor -%}

{{ names_by_code | json }} ```

In a featured products block holding two products coded TEE-01 and CAP-02, this outputs {"TEE-01":"Classic tee","CAP-02":"Canvas cap"}.

UUID and random numbers

```liquid

{%- new UUID request_ref -%} {%- new Rand dice min: 1, max: 6 -%}

Reference {{ request_ref }}: you rolled {{ dice }}.

```

request_ref holds a value such as 550e8400-e29b-41d4-a716-446655440000, and dice holds a whole number from 1 to 6. Both change on every render. Inside a {% cache %} block, the cached output keeps the first value until the block expires.

Was this article helpful?

Was this article helpful?