Storefront blocks

​

Declare a block

[[data.definitions]]
owner      = "product"
key        = "rating"
type       = "json"
visibility = "storefront"

[[storefront.blocks]]
handle     = "product-rating"
template   = "blocks/product-rating.liquid"
stylesheet = "blocks/product-rating.css"
name       = { ar = "تقييم المنتج", en = "Product rating" }
target     = "product"
data       = ["product.rating"]

  [[storefront.blocks.settings]]
  key     = "accent_color"
  type    = "color"
  label   = { ar = "اللون", en = "Colour" }
  default = "#0b6e4f"

• target: product for the product page (the template reads product), or any (the default) for any page but checkout.
• data: the app data keys the block reads, as <owner>.<key>. Each must be declared with storefront visibility. Owners: product (target product only), store, business. Order and customer data never reach a store page.
• settings: what the merchant sets in the builder. Types: string, text, boolean, integer, number, select, color, image, url, product, collection. A value that no longer fits the declaration falls back to the default when the block renders.

​

The template

<section class="rating">
  {%- assign rating = app.data.product.rating -%}
  {%- if rating %}
  <p>{{ rating.average | stars }} <small>({{ rating.count }})</small></p>
  {%- else %}
  <p>{{ product.name }}: no reviews yet</p>
  {%- endif %}
  <img src="{{ product.image | image_url: 320 }}" alt="{{ product.name }}">
</section>

​

Objects

​

Tags

​

Filters

​

The HTML a block may use

• Elements: a, abbr, article, aside, b, bdi, bdo, blockquote, br, caption, cite, code, dd, del, details, dfn, div, dl, dt, em, figcaption, figure, footer, h2 to h6, header, hr, i, img, ins, kbd, li, mark, meter, ol, p, pre, progress, q, s, samp, section, small, span, strong, sub, summary, sup, the table elements, time, u, ul, var, wbr. No h1: the page has its own.
• SVG icons: svg with g, path, circle, ellipse, line, polygon, polyline, rect and a text-only title inside it, with their shape and paint attributes (fill="currentColor" follows the text colour).
• Attributes: class, title, lang, dir, role, hidden, translate, a set of aria-*, and each element’s own (href and target on links; src, alt, width, height on images; colspan, datetime, open, …). No id or name: an element with an id becomes a global variable of the page, which can break the store’s own scripts. No style (use the stylesheet), no data-*, no on… handler.
• Links: https:// addresses (Tassyir adds rel="nofollow noopener noreferrer"), paths on the store (/collections/all) and fragments.
• Images: an <img> takes its src from {{ … | image_url: <width> }} only, so every image comes from Tassyir’s CDN. Images load lazily.
• Text: bidirectional override and isolate characters, zero-width and control characters are removed from values; Arabic’s marks and joiners stay.

​

The stylesheet

• an at-rule other than @media, @supports and @keyframes <plain name> (no @import, @font-face, @layer), or a nested rule;
• a url() outside https://cdn.tassyir.io/, or a function that loads something (image-set(), src());
• position other than static, relative, absolute or sticky, written as the word itself (never fixed, never through var()); behavior, -moz-binding, expression();
• a backslash escape outside a quoted string, <, a bidi or invisible character.

.rating {
  color: var(--block-accent-color);
  background: var(--st-surface);
  border-radius: var(--st-radius);
  padding: var(--st-space);
}
.rating small {
  color: var(--st-muted);
}

​

Limits

​

Test a block on your machine

import {
  renderBlock,
  sampleBlockContext,
  validateBlock,
} from '@tassyir/storefront-blocks';
import type { BlockDeclaration } from '@tassyir/storefront-blocks';
import { readFileSync } from 'node:fs';

const declaration: BlockDeclaration = {
  target: 'product',
  settings: [{ key: 'accent_color', type: 'color', default: '#0b6e4f' }],
  data: ['product.rating'],
};
const template = readFileSync('blocks/product-rating.liquid', 'utf8');
const stylesheet = readFileSync('blocks/product-rating.css', 'utf8');

const check = validateBlock({ template, stylesheet, declaration });
if (!check.ok) {
  for (const error of check.errors) {
    console.error(
      `${error.source}:${String(error.line)}:${String(error.column)} ${error.code}: ${error.message} ${error.fix}`,
    );
  }
}

for (const language of ['ar', 'fr', 'en'] as const) {
  const preview = renderBlock(
    template,
    sampleBlockContext(declaration, {
      language,
      appData: { product: { rating: { average: 4.4, count: 128 } } },
    }),
    declaration,
  );
  console.log(language, preview.ok ? preview.html : preview.errors);
}

​

Errors