Filters, Tags & Helpers

Filters Overview

Nimbu extends the standard Liquid filter set with e-commerce, formatting, API, and infrastructure helpers. Below is a categorized reference.

Analytics

Filter	Description
`google_analytics_tag`	Outputs a Google Analytics tracking snippet from a tracking ID.
`google_analytics_ecommerce_code`	Generates GA e-commerce conversion markup for a given `order`.

API & JSON Helpers

Filter	Description
`json`	Serializes an object to JSON. Accept optional `without:` argument to omit keys.
`from_json`	Parses a JSON string into a Liquid object (hash or array).
`api_sso_info`	Produces API SSO meta headers (`X-Nimbu-*`) for a given API token.
`to_geopoint`	Converts coordinates to `{ lat, lng, latitude, longitude }` JSON.
`is_geopoint`	Checks whether an object represents a coordinate.

Commerce & Cart Helpers

Filter	Usage
`add_to_cart`	Renders an add-to-cart form. Options: `btn_class`, `add_label`, `default_quantity`, `hide_variants`, `input_class`, `show_quantity_dropdown`, `show_quantity_buttons`, `hide_quantity`.
`update_cart_item`	Renders a quantity update form for an order line item. Options: `show_quantity_dropdown`, `show_quantity_buttons`, `show_refresh_btn`, `refresh_btn_class`, `refresh_btn_label`.
`delete_cart_item`	Renders a remove-from-cart button. Options: `delete`, `confirm`, `class`.
`delete_cart_group`	Removes grouped cart items. Same options as `delete_cart_item`.
`checkout_button`	Generates a checkout button. Options: `label`, `class`.
`payment_form`	Outputs a payment-method selection form during checkout. Options: `id`, `class`, `title`, `value`, `button_class`.
`auto_apply_coupon`	Applies a coupon once the page loads. Pass the coupon code as input.
`money_with_currency`, `money_without_currency`, `number_to_currency`	Format amounts with locale-aware currency formatting (`unit`, `precision`, `locale`, `format`, `negative_format`, `separator`, `delimiter`, `fancy`).
`weight`, `weight_with_unit`	Convert grams to kilograms, optionally appending the unit.

Filters mirror Rails number helpers (number_to_human, number_to_human_size, number_to_percentage, number_to_phone, number_with_delimiter, number_with_precision). All accept optional arguments for precision, locale, delimiters, and units.

Date & Time

Filter	Description
`to_datetime`	Parses strings into `DateTime`.
`localized_date`	Formats dates using locale-specific presets (`default`, `long`, `short`, `time`, `full`, `date_only`) or a custom `strftime` string. Optional arguments: `format`, `locale`.
`time_ago_in_words`	Produces human-friendly relative timestamps (“1 hour ago”).

CDN & Asset Helpers

Filter	Description
`asset_url`	Builds a CDN URL from an asset path (`site` CDN aware).
`stylesheet_tag`	Generates a `<link>` tag for a CSS asset. Options: `media`, `rel`, `type`.
`javascript_tag`	Generates a `<script>` tag for a JS asset. Option: `type`.
`theme_image_url`	Resolves a theme image file to its CDN URL.
`download`	Appends `?dl=1` to a CDN asset and sets `Content-Disposition: attachment`.
`auto_discovery_link_tag`	Emits an RSS/Atom discovery `<link>` tag.

Pagination

default_pagination – Renders pagination markup for a paginate object. Options: previous_label, next_label, css, style (zurb, bootstrap, bootstrap4).

Image Processing

Use the chain \{\{ 'image.png' \| theme_image_url \| filter, width: '300px', cropping: 'fill' \}\} with these helpers:

filter – Applies transformations (width, height, cropping, gravity, effect).
grayscale, sepia, vignette – Shortcuts for common effects.

Text & Utility

Filter	Highlights
`downcase`, `upcase`, `capitalize`	Standard case transformations.
`textile`, `markdown`	Convert markup to HTML.
`emoticize`	Replaces emoticons with emoji images.
`replace_by_regex`	Regex-based substitution using Ruby syntax.
`parameterize`, `transliterate`	Friendly URL slugs and ASCII conversions.
`to_i`, `to_f`	Numeric conversions.
`strip`, `strip_html`, `truncate`, `truncatewords`	Text normalization utilities.
`concat`	Concatenates strings or arrays.
`is_empty`	Tests for blank/whitespace-only strings.
`uri_encode`, `uri_decode`	Percent-encode/decode strings.
`keys`, `values`	Extract keys or values from hashes.
`sort`, `numeric_sort`	Sorting helpers for arrays and drops (support dot notation, see below).
`group_by`, `group_by_exp`	Group arrays by property or custom Liquid expression.
`where`, `where_exp`, `find`, `find_exp`	Filter arrays/hashes by property or expression.
`intersection`, `union`, `push`, `pop`, `shift`, `unshift`	Array set manipulation.
`country`	Lookup country metadata by ISO code.
`gravatar`	Build a Gravatar URL with fallback options.
`random`	Generate random integers (`random` or `random: min`).

Math & Validation

Filter	Description
`modulo`	Modulo operation with optional offset.
`is_number`, `is_float`	Validity checks for numeric inputs (strings included).
`random`	Random integer generation with optional min/max.

Cryptography

Filter	Description
`base64_encode`, `base64_decode`	Base64 transformations.
`md5`, `sha1`, `sha224`, `sha256`, `sha384`, `sha512`	Hash functions.
`hmac256`	HMAC SHA-256 for signing payloads (`secret:` option).

QR Codes

Filter	Description
`qr`	Renders a PNG QR code (`size`, `fill`, `color`).
`qr_datauri`	Inline QR as a data URI.
`qr_svg`	Outputs SVG markup (`fill`, `color`).
`qr_html`	Generates an HTML table representation (style it with CSS for emails).

URL Query Helpers

add_query_params – Appends query params to a URL.
download – Converts a CDN asset URL into an attachment download link.

Tags Overview

Layout & Includes

Tag	Purpose
`{% layout %}`	Swap layouts dynamically.
`{% include 'snippet' %}`	Include snippets (alias for `snippet` tag).
`{% snippet 'name' %}`	Render a snippet with optional parameters.

Data Selection

Tag	Description
`{% paginate collection by n %}`	Paginate arrays or drops. IMPORTANT: Iterate `paginate.collection`, not the original collection. Use `\{\{ paginate \| default_pagination \}\}` for controls.
`{% scope ... %}`	Restrict channel, product, or collection queries with logical expressions (`==`, `!=`, `<`, `>`, `in`, `nin`, `exists`, `contains`, `start`, `end`, `regex`).
`{% sort ... %}`	Apply server-side sort orders for scoped collections.
`{% with_scope ... %}`	Temporarily scope queries within a block.
`{% tree %}`	Render page trees.
`{% search %}`	Execute configured search queries.
`{% translate %}`	Fetch copywriting strings with fallbacks and interpolation.
`{% set variable, key, value %}`	Construct key/value maps dynamically.

Control Flow

Nimbu overrides the standard for and if tags to add features:

{% for item in collection, limit: 4, skip: 2, cache: cache_key %} – Supports cache: to memoize output.
{% if %} – Supports expressions consistent with the scope parser (and, or, parentheses, comparisons, regex, contains).

Tag	Description
`{% nav slug %}`	Render menu markup. Options: `depth`, `exclude`, `no_wrapper`, `id`, `class`, `link_class`, `item_class`, `submenu_class`, `submenu_wrapper_class`, `active_item_class`, `active_parent_class`.
`{% breadcrumbs %}`	Output breadcrumbs for the current page hierarchy.
`{% localized_path 'nl' %}`	Resolve the current page path for another locale.

Analytics & Tracking

Tag	Description
`{% google_analytics %}`	Injects the GA snippet manually.
`{% analytics %}`	Generic analytics loader hook.
`{% safari_push_js %}`	Safari push notifications helper.
`{% oauth2_consent_form %}`	Renders OAuth consent flows.
`{% theme_liquid_version %}`	Exposes the active Liquid runtime semantics.
`{% consent_manager %}`	Outputs the consent manager UI entrypoint.

Editable Content

Tag	Description
`{% editable_field %}`	Single-line editable text. Optional `label`, `hint`, `assign`.
`{% editable_text %}`	WYSIWYG content block.
`{% editable_file %}`	Asset picker; can be embedded within attributes.
`{% editable_select %}`	Dropdown with `options:` and `labels:` list.
`{% editable_switch %}`	Boolean toggle.
`{% editable_reference %}`	Reference to channels, customers, products, collections, menus, or pages (`to:`).
`{% editable_group %}`	Group multiple editables under a collapsed group with optional `settings`.
`{% editable_canvas %}`	Define a canvas zone, optionally nested.
`{% repeatable %}`	Create repeatable blocks inside groups or canvases.

Tag	Description
`{% login_with provider: 'facebook' %}`	Start OAuth login/linking flows.
`{% unlink_from provider: 'twitter' %}`	Disconnect providers.
`{% consume %}`	Read values from deferred content for reuse.

Snippet Caching

{% cache key %}...{% endcache %} – Cache arbitrary Liquid fragments.

Sorting & Conditions

{% sort field asc, other desc %} – Multi-field ordering for scoped channels.
{% condition %}, {% scope %} – Compose complex logical expressions for filtering.

Forms & Inputs (Liquid Form Tags)

Drops::Forms registers a comprehensive set of tags for form creation. Common patterns:

{% form channels.contact, class: 'form' %}
  {% hidden_field 'redirect_after_submit', value: '/thank-you' %}
  {% input 'name', label: 'Name', required: true %}
  {% input 'email', as: 'email', label: 'Email' %}
  {% inputs_for_fields %}
  {% submit_tag 'Send', class: 'btn btn-primary' %}
{% endform %}

Available field tags include input, hidden_field, text_area, password_field, check_box, file_field, select_tag, collection_select, date_select, time_select, multi_date_tag, and more. Most accept HTML attribute overrides (class, placeholder, min, max, etc.).

Additional helpers:

{% error_messages_for object %} – Renders validation messages.
{% form_tag %} / {% simple_form_tag %} – Generic form wrappers when not bound to a channel or model.
{% inputs_for_fields %} – Autogenerates inputs for channel-defined fields.
{% input_tag_template %} – Customize the rendering template of a specific widget type.
form_model – Access the bound object inside the form for values and errors.

When redirecting after submit, include a hidden redirect_after_submit field. Nimbu automatically persists field values and exposes validation errors via .inline-error CSS classes.

Copywriting & Translation

Use {% translate %} blocks for translatable strings and provide descriptive keys. You can pass variables with named parameters and use %{placeholder} syntax inside the default text.

Best Practices

Chain filters for complex transformations: \{\{ product.price \| money_with_currency \| replace: ',', ' ' \}\}.
Provide cache keys for loops and capture localized strings within the key when caching.
Use where_exp/find_exp for complex boolean logic instead of nested if statements.
Validate URLs before passing to filters expecting CDN paths to avoid runtime errors.
For email-friendly QR codes, prefer qr_html and include the CSS snippet from the legacy reference.

Refer back to this page whenever you need the syntax or supported options for a filter or tag.