{ "version": 1, "what": "Your own markup on shop data. You write plain HTML and CSS; where you need shop data or live behaviour you add a vz- attribute. {{ … }} substitutes values.", "keys": [ { "name": "vz-menu", "value": "optional", "since": "1", "does": "Marks the element as the shop menu: the platform wires opening and the active item.", "example": "", "runs": "browser" }, { "name": "vz-search", "value": "none", "since": "1", "does": "Turns the input into catalogue search.", "example": "", "runs": "browser" }, { "name": "vz-cart-open", "value": "none", "since": "1", "does": "Opens the cart on click.", "example": "", "runs": "browser" }, { "name": "vz-cart-count", "value": "optional", "since": "1", "does": "Renders the live number of items in the cart.", "example": "0", "runs": "browser" }, { "name": "vz-add-to-cart", "value": "optional", "since": "1", "does": "Adds the current product to the cart, honouring the chosen variant.", "example": "", "runs": "browser" }, { "name": "vz-fav", "value": "optional", "since": "1", "does": "Toggles the product in the wishlist.", "example": "", "runs": "browser" }, { "name": "vz-variants", "value": "none", "since": "1", "does": "Marks the block of variant choices (sizes, colours); the platform binds selection to price and cart.", "example": "
…
", "runs": "browser" }, { "name": "vz-gallery", "value": "none", "since": "1", "does": "Marks the gallery root; pairs with vz-gallery-main and vz-gallery-thumbs.", "example": "
…
", "runs": "browser" }, { "name": "vz-gallery-main", "value": "none", "since": "1", "does": "The large frame of the gallery.", "example": "\"\"", "runs": "browser" }, { "name": "vz-gallery-thumbs", "value": "none", "since": "1", "does": "The thumbnails strip: clicking (or hovering on desktop) switches the main frame.", "example": "
\"\"
", "runs": "browser" }, { "name": "vz-lead", "value": "required", "since": "1", "does": "Opens the lead form with the given id.", "example": "", "runs": "browser" }, { "name": "vz-quickview", "value": "required", "since": "1" }, { "name": "vz-modal", "value": "required", "since": "1" }, { "name": "vz-toggle", "value": "optional", "since": "1", "does": "Toggles the state named in the attribute — for tabs, accordions, drawers.", "example": "", "runs": "browser" }, { "name": "vz-state", "value": "required", "since": "1", "does": "Shows the element only while the named state is on.", "example": "
…
", "runs": "browser" }, { "name": "vz-for", "value": "required", "since": "1", "does": "Repeats the element for every item of a list from the page scope.", "example": "
  • {{ m.name }}
    • ", "runs": "server" }, { "name": "vz-if", "value": "required", "since": "1", "does": "Drops the element when the value is empty or false.", "example": "
    {{ product.old_price_text }}
    ", "runs": "server" }, { "name": "vz-src", "value": "required", "since": "1", "does": "Sets src from the scope.", "example": "\"\"", "runs": "server" }, { "name": "vz-href", "value": "required", "since": "1", "does": "Sets href from the scope. Addresses come canonical (tree paths), so links never bounce through a redirect.", "example": "{{ m.name }}", "runs": "server" }, { "name": "vz-edit", "value": "required", "since": "1", "does": "Marks the text as editable in the visual editor. No effect on the live site.", "example": "

    {{ product.name }}

    ", "runs": "browser" }, { "name": "vz-app", "value": "required", "since": "1", "does": "Mounts your script in a sandbox frame (level 2). For a full page with scripts inline use document level 3 instead.", "example": "
    ", "runs": "browser" }, { "name": "vz-sticky", "value": "none", "since": "1", "does": "Keeps the element pinned while the page scrolls.", "example": "
    …
    ", "runs": "browser" } ], "scope": { "note": "Available inside {{ … }} and to your script as window.vz (script id=\"vz-page-data\"). One object serves both, so a value never differs between markup and script.", "shop": [ "name", "initial", "currency", "logo_url" ], "product": [ "id", "name", "sku", "description", "price", "price_text", "old_price", "old_price_text", "url", "preview_url", "gallery[].url", "gallery_items[].kind", "gallery_items[].url", "gallery_items[].poster_url", "gallery_items[].html", "gallery_items[].caption", "galleries[].id", "galleries[].name", "galleries[].images[].url", "shown_gallery.id", "shown_gallery.name", "tags[]", "rating_avg", "rating_count", "attributes[].name", "attributes[].value", "promotions[].id", "promotions[].name", "promotions[].description", "promotions[].kind", "promotions[].icon", "promotions[].theme", "combo_items[]", "in_combos[]", "variants" ], "gallery": { "note": "preview_url and gallery[] are the IMAGES of the CURRENT set (?v=), the same ones the platform card shows: a set bound to a gallery gives that gallery’s images only; a set without a binding gives the preview plus the first gallery. gallery[0] is preview_url, so a thumbs strip over gallery already includes the main frame.", "items": "A gallery item is not always an image. gallery_items[] is the same slider with roles: kind is image | video | audio | html (the server derives it from the file type; only html is authored). url is the media file, poster_url the video poster or audio cover, html the embed code, caption the optional line under the slide. gallery[] keeps only kind=\"image\", because that is what an can show — branch on kind yourself when you want to render video or an embed. New roles may appear, so treat kind as open and ignore what you do not handle.", "galleries": "galleries[] is the full list of the product’s named galleries (by colour and so on); the first one is the default gallery. A gallery is a shop-level resource, so the same one can sit on several products. shown_gallery is the gallery currently shown — the set’s own, or the first one when the set has no binding; null when the product has none, so guard a caption with vz-if. It is NOT called \"gallery\": that name is already the current set’s frames. images[] of a gallery that is not the shown one carries ONE cover frame, not the whole set: the page asks the card endpoint for the shown gallery only, because a product photographed in 360° for a dozen colours would otherwise ship hundreds of frames nobody looks at. A colour switcher needs the cover; the frames themselves arrive when ?v= switches the page, or from GET /galleries/{id}.", "example": "

    Photos: {{ product.shown_gallery.name }}

    \"\"
    " }, "combos": { "note": "Two lists, and they answer different questions. combo_items[] is what a SET contains — use it on the set’s own card. in_combos[] is the sets a COMPONENT belongs to — use it on an ordinary product card to say \"cheaper as part of a set\". Both are already on product; neither costs an extra request.", "in_combos": [ "name", "url", "preview_url", "benefit", "benefit_text", "combo_price", "combo_price_text", "components_total", "components_total_text", "item_price", "item_price_text", "item_regular_price", "item_regular_price_text", "item_times_cheaper_x100", "item_times_cheaper_text" ], "combo_items": [ "name", "url", "preview_url", "quantity", "price_text", "base_price", "base_price_text", "effective_price", "effective_price_text" ], "pairs": "Every number has a ready string beside it, because substitutions have no expressions: {{ c.item_price }} sorts, {{ c.item_price_text }} prints. item_times_cheaper_text is a NUMERAL (\"2,5\"), not a sentence — you write the words: \"дешевле в {{ c.item_times_cheaper_text }} раза\". The separator follows the shop currency, so it matches the money already on the page.", "honesty": "item_times_cheaper_text is EMPTY whenever a ratio would overstate: no benefit, same price, dearer in the set, or a cut below 1.1× (where truncation would print \"1\" and your sentence would read \"cheaper by 1 times\"). Rounding is always DOWN — 1.97× prints 1,9 — so the page never promises more than the cart delivers. Guard the line with vz-if and it disappears on its own.", "gift": "A free component is item_price 0 with item_regular_price above 0, and its ratio is empty on purpose — there is no ratio against zero. Render a gift from item_price == 0, not from the ratio. When item_regular_price is 0 there is simply nothing to say — the component costs nothing on its own — so the texts are empty rather than \"0 ₽\", which a shopper reads as \"free\".", "why_a_set_can_be_silent": "The in-set price is computed from the BASE price, never from the promotional one, so that a set does not change price every time a component goes on sale. A deep enough discount on a component can therefore make it cheaper on its own than inside the set — and then the ratio is 0 and the line disappears. That is correct, not a bug. Never compute your own ratio from the two prices: this is exactly where it would disagree with the cart.", "example": "

    В наборе «{{ c.name }}» — {{ c.item_price_text }} вместо {{ c.item_regular_price_text }}, дешевле в {{ c.item_times_cheaper_text }} раза

    " }, "category": [ "id", "name", "description", "url" ], "products": { "note": "Products of the CURRENT section, live. This is what makes an own-markup row honest: before it existed, prices had to be typed into the document and went stale the moment the catalogue changed. Loaded only when the document asks for it — write vz-for=\"p in products\" — so a page that does not use it pays nothing. Up to 48 items; preview is already a resizer path, so an ordinary is a thumbnail rather than a multi-megabyte original.", "fields": [ "id", "name", "sku", "price", "price_text", "old_price", "old_price_text", "url", "preview", "in_stock", "promotion_name" ], "promotions": "price and old_price already account for promotions — the server runs every card through the same engine the cart uses. promotion_name is the rule that fired, empty when none did. Deliberately absent: the discount amount (derive it from the two prices, or your number will drift from ours on rounding), the validity period (it belongs to the rule, and several rules can cover one product), and any \"price with a promo code\" flag — coupon-gated rules never reach a card, because a storefront must not promise a discount that does not exist without the code, and a personal price in a shared page scope would leak someone else’s coupon.", "example": "
    \"\"

    {{ p.name }}

    {{ p.price_text }}
    " }, "menu": [ "name", "url", "img", "children[]" ], "crumbs": [ "name", "url" ], "company_id": "number", "empty": "product is null on any page that is not a product page; category likewise. Guard with vz-if so the node disappears instead of rendering blanks." }, "markup_contract": { "note": "Classes, variables and attributes the platform guarantees and will not rename. Anything not listed here is internal and may change without notice — the previous run relied on several of these after reading them off the live page, which is a fair complaint: if we hand out hooks, we owe you a list of the stable ones.", "where_legend": { "note": "Every entry says WHERE it exists, because an html block renders inside a shadow root and the two sides do not see each other’s CSS. Targeting the wrong side is silent: the rule is valid, it simply matches nothing.", "page": "Lives in the page document, outside any shadow root. Reachable from global CSS and from ordinary document.querySelector.", "shadow": "Lives INSIDE the shadow root of an html block. Global CSS cannot reach it — put the rule in the block’s own