Malliviite

Koodieditorin avaaminen kerrotaan sivulla Oma koodi komponentissa.

Missä: suunnittelutyökalu, komponentin Customize with code › Code, tilassa Advanced. Osio Custom component noudattaa samoja sääntöjä.

#Juuri on kaupan

Jokaisella komponentilla on juuri, jonka kauppa piirtää. Mallisi on juuren sisältö.

• Ylätunnisteen juuri on [data-bs-header]. Kauppa asettaa juureen tilat [data-bs-transparent], [data-bs-scrolled] ja [data-bs-sticky], myös kun ylätunniste on omaa HTML:ääsi.
• Älä kirjoita malliin omaa <header>-elementtiä. Aloita siitä, mitä sen sisään tulee.
• CSS:si rajataan juureen. JS:si saa juuren muuttujana root.
• Custom component -osion juuri on [data-bs-block="<osion-id>"].

Kaikki juuret ovat sivulla Koukut ja CSS-viite.

#Mallisyntaksi

Malli on HTML:ää, jossa muuttujat ovat kaksinkertaisissa aaltosulkeissa. Tämä on koko syntaksi.

• Tyhjä teksti, 0, tyhjä lista ja false ovat epätosia.
• HTML:ää ei voi tulostaa ilman escapausta.
• Apufunktioita ja sisällytettäviä malleja ei ole.

#Rajat

• Pidempi osa katkaistaan varoituksella, joka kertoo kohdan, esimerkiksi css cut at 200 000 characters.
• Piirto keskeytyy 50 000 askeleen jälkeen. Silmukka silmukassa ei voi jumittaa kauppaa.
• Vähintään 33 333 merkin malli piirretään suunnittelutyökalussa kerran ilman dataa. Jos se silloin osuu rajaan, se näkyy kohdassa May cut with some data välilehdellä Code.
• Kauppa listaa vain sen, minkä sen oma piirto katkaisee.

#Virheet ja varoitukset

Malli, jota ei voi lukea, ei piirrä mitään. Tämä koskee esimerkiksi {{#each}}-lohkoa, jota ei koskaan suljeta, tai lohkoa, joka suljetaan väärällä tagilla. Kauppa näyttää silloin vakioulkoasun, ja suunnittelutyökalu näyttää virheen koodin kohdalla.

Varoitus voi koskea CSS-sääntöä, jota ei voitu rajata, tai vaihtoehtoa, joka hylättiin.

#Muuttujat

#Header, Menu panel ja Footer

Nämä kolme jakavat yhden muuttujajoukon. Osio Custom component saa saman joukon.

#Product card

Yksi malli korttia kohti. Se piirretään jokaiselle ruudukon tuotteelle.

#Product page

Galleria ja ostopaneeli, piirrettynä näytettävälle variantille. Kun asiakas valitsee toisen variantin select-variant-actionilla, malli piirretään uudelleen. Hinta, tuotenumero, varastorivi, product.variantId ja jokainen selected seuraavat mukana. Muu osa sivusta on vakiosivua: tiedot, arvostelut ja liittyvät tuotteet. Mallin alle kauppa piirtää tuotteen kysymykset, rivin ostoskorin lisävalinnoista ja ruudun Optional add-ons. Mallin add-to-cart lisää asiakkaan rastittamat lisävalinnat ja pysähtyy tyhjään pakolliseen kysymykseen kuten vakiopainike.

#Gallery

Tuotekuvat tuotesivulla. Jos tuotesivu on omaa HTML:ää, sen malli piirtää gallerian itse, eikä gallerian ulkoasua piirretä lainkaan. Koodieditori, kaupan raportti ja työtila kertovat sen.

#Category

Kokoelmasivu ja sen listaamat tuotteet: kategoria, All products tai hakutulokset. Malli saa sivun suodattimet datana kohdassa filters[]: jokainen ryhmä arvoineen, määrineen, rasteineen ja linkkeineen, jotka rastittavat arvon tai poistavat rastin. Kauppa ei lisää suodattimia mallin omaan HTML:ään. Malli listaa sen, mitä osoitteen parametrit (?sort=…&f.…&category=…) määräävät. Malli korvaa Collection-sivun osiot, tuoteruudukko mukaan lukien. Sivun oma CSS (Collection-sivun välilehti Code) on edelleen voimassa.

#Banner

Osion omat asetukset.

Kirjoita otsikko <h1>-elementtinä, kun banneri on sivun otsikkolohko. Silloin se on sivun otsikko. Jos mallista puuttuu <h1>, kauppa lisää bannerin jälkeen piilotetun sivun otsikon, kun banneri on sivun otsikkolohko. Banneri on otsikkolohko, kun se on sivun ensimmäinen banneri tai hero eikä mikään tason 1 otsikko-osio ota otsikkoa.

#Actionit

HTML:lläsi ei ole omia tapahtumankäsittelijöitä. Lisää elementtiin data-bs-action, niin kauppa hoitaa loput napsautuksella. Kauppa käyttää samoja kuuntelijoita kuin vakio-HTML:ssä. Attribuutti voi olla missä tahansa elementissä, myös <svg>-elementissä.

• Jos vaadittu attribuutti puuttuu, napsautus ei tee mitään.
• data-bs-quantity-arvon on oltava positiivinen kokonaisluku. Muu luetaan arvona 1.
• Action, jota ei ole tai jolta puuttuu vaadittu attribuutti, antaa varoituksen mallin kääntämisen yhteydessä. Varoitus näkyy koodin kohdalla ja kaupan HTML:ssä muodossa <!-- bs-component-warning: … -->.
• subscribe-newsletter vaatii lomakkeen, jossa on data-bs-newsletter ja kenttä name="email". Se ajetaan, kun lomake lähetetään, joten Enter kentässä toimii. Osoite saa saman tarkistuksen ja saman vastauksen kuin vakioalatunnisteessa.

add-to-cart ilman data-bs-variant-id:tä, esimerkiksi kortilla, kysyy kaupalta tuotteesta:

#Koukut

Koukut ovat kaupan HTML:n attribuutteja, joihin CSS ja JS kohdistuvat: komponentin juuri, sisäelementit ja juuren tilat. Kaikki koukut komponenteittain, sivun koukut ja tokenien CSS:n säännöt ovat sivulla Koukut ja CSS-viite.

#Puhdistus

Piirretty malli puhdistetaan ennen kuin se päätyy sivulle, samalla tavalla palvelimella ja selaimessa.

Säilytettävät attribuutit:

• kaikissa elementeissä: class, id, title, role, tabindex, lang, dir, hidden, style, translate, kaikki aria-*, kaikki data-bs-* ja data-footer-*
• linkeissä: href, target, rel
• kuvissa: src, srcset, sizes, alt, width, height, loading
• painikkeissa ja kentissä: type, name, value, placeholder, disabled
• form-elementissä: action, kun se on kaupan polku, esimerkiksi /search, ja method, kun se on get tai post
• SVG:ssä: viewBox, fill, stroke, stroke-width, d, points ja muut piirtoattribuutit

Mitä poistetaan:

• script, style, iframe, object, embed, noscript, template, textarea, select, video, audio, canvas, dialog, math ja title koko sisältöineen
• kaikki on*-attribuutit ja kaikki kommentit
• muut data-*-attribuutit kuin data-bs-* ja data-footer-*
• osoitteet, jotka eivät ole suhteellisia, https:, http:, mailto: tai tel:, paitsi data:-kuvat img-elementissä
• action, joka osoittaa kaupan ulkopuolelle

Elementti, jota ei ole listassa, poistetaan, mutta sen sisältö säilyy. style="…" puhdistetaan kuten muu CSS. Linkeissä säilyvät target="_blank", joka saa rel="noopener", sekä target="_self". Muut target-arvot poistetaan. Avoimet elementit suljetaan lopussa, joten tulos on aina tasapainoista HTML:ää.

#Luokat ja koot

Vakio-HTML:ssä on muutama Tailwind-luokka, esimerkiksi flex, items-center ja gap-4. Suunnittelutyökalu ei käännä mallistasi uusia luokkia. Luokka, jota kaupassa ei jo ole, ei tee mitään. Aseta koko ja välit välilehdellä Design, kohdassa Code › CSS koukkuihin tai elementin style-attribuuttina.

#CSS

Code-välilehden CSS koskee vain komponenttia. Miten valitsimet rajataan juureen, mitä puhdistus poistaa ja miten lataat omat fontit, kerrotaan sivulla Koukut ja CSS-viite.

px ja rem: katso Oma CSS ja head-koodi.

#JS

• JS ajetaan kerran sivun latausta kohti, kun sivu on latautunut, jokaisella sivulla, jolla komponentti on.
• Se saa komponentin juurielementin muuttujana root. Jos komponenttia ei ole sivulla, sitä ei ajeta.
• Valikkopaneelin juuri on olemassa vain, kun paneeli on auki. Sen JS ajetaan joka kerta, kun paneeli avataan, uutta juurta vasten. Sido kuuntelijat muuttujaan root, ei document-olioon.
• Virhe, myös syntaksivirhe, kirjataan selaimen konsoliin tyylin nimellä. Se ei pysäytä sivua eikä muiden komponenttien JS:ää.
• Koodi ajetaan myös työtilassa. Kytkin Run JS in the builder keskeyttää sen siellä istunnon ajaksi. Kauppa ja Preview (⌘P) ajavat sen tavalliseen tapaan.

root.querySelectorAll('[data-bs-header-icons] a').forEach((a) => {
  a.addEventListener('mouseenter', () => a.classList.add('is-hot'));
});

Tuotekortti on sivulla monta kertaa. root on silloin ensimmäinen kortti. Käytä kaikille document.querySelectorAll('[data-bs-card]').

Sivun JS välilehdellä Code ajetaan samalla tavalla, ilman muuttujaa root. Se, mitä kirjoitat Collection-sivulle, koskee kaikkia kategoriasivuja.

#Esimerkki: navbar Classic-kaupassa

Tavoite on täysleveä ylätunniste. Se on läpinäkyvä hero-kuvan päällä valkoisella logolla ja valkoisilla kuvakkeilla, ja valkoinen, kun sivua on vieritetty 24 px. Oikealla on neljä 30 px:n kuvaketta: haku, toivelista, ostoskori ja valikko. Suurin osa on säätimiä. Loput on kuusi riviä CSS:ää.

Säätimet komponenttipaneelissa kohdassa Header:

1. Vaihda etusivun tekstihero Image banner -osioon, jonka Width on täysi ja kuva tumma.
2. Valitse Look: Icons + panel.
3. Aseta Options: Sticky päälle, Transparent over hero päälle, Menu label pois, Search päälle, Cart päälle, Announcement bar pois.
4. Valitse kohdassa Content musta logo kenttään Logo korkeudella 40. Valitse valkoinen kenttään Light logo.
5. Tarkista, että Theme › Colours › Header text over hero on valkoinen.

Kytke Advanced päälle, paina Customize with code ja kirjoita kohtaan Code › CSS:

[data-bs-header] { padding: 16px; }
@media (min-width: 768px) { [data-bs-header] { padding: 32px; } }
[data-bs-header-inner] { max-width: none; }
[data-bs-header-icons] { gap: 16px; }
[data-bs-header-icons] a, [data-bs-header-icons] button { opacity: 1; }
[data-bs-header-icons] svg { width: 30px; height: 30px; stroke-width: 1.6; }

Paina Save as new style ja anna tyylille nimi "Oma navbar". Tyyli on nyt kohdassa Your header styles kaikissa workspacen kaupoissa. Logot kuuluvat teemaan, ja ne asetetaan kohdassa Content jokaisessa kaupassa.

#Sama navbar omana HTML:nä

Avaa Code › HTML ja paina Start from the standard markup. Kenttä täyttyy vakioulkoasun HTML:llä. Alla oleva malli on sama navbar käsin kirjoitettuna. Se käyttää samoja sisäisiä koukkuja, joten yllä oleva CSS toimii sellaisenaan. Hampurilaisvalikko avaa kaupan vakiopaneelin, jossa on oma Close-painike ja joka sulkeutuu Escillä.

<div data-bs-header-inner>
  <a href="/" aria-label="{{storefront.name}}">
    <img src="{{brand.logoUrl}}" alt="{{storefront.name}}" height="{{brand.logoHeight}}" class="logo-dark">
    <img src="{{brand.footerLogoUrl}}" alt="" height="{{brand.logoHeight}}" class="logo-light">
  </a>
  <div data-bs-header-icons>
    <button type="button" data-bs-action="open-search" aria-label="{{i18n.search}}">
      <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.6" stroke-linecap="round" aria-hidden="true"><circle cx="11" cy="11" r="7"/><path d="m20 20-3.5-3.5"/></svg>
    </button>
    <a href="/wishlist" data-bs-wishlist-icon aria-label="{{i18n.wishlist}}">
      <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.6" stroke-linecap="round" aria-hidden="true"><path d="M20.8 4.6a5.5 5.5 0 0 0-7.8 0L12 5.7l-1-1.1a5.5 5.5 0 0 0-7.8 7.8L12 21l8.8-8.6a5.5 5.5 0 0 0 0-7.8z"/></svg>
    </a>
    <button type="button" data-bs-action="open-cart" data-bs-cart-icon aria-label="{{i18n.cart}}">
      <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.6" stroke-linecap="round" aria-hidden="true"><path d="M6 6h15l-1.5 9h-12z"/><circle cx="9" cy="20" r="1"/><circle cx="18" cy="20" r="1"/><path d="M6 6 5 3H2"/></svg>
      <span data-bs-cart-count>{{cart.count}}</span>
    </button>
    <button type="button" data-bs-action="open-menu" data-bs-menu-button aria-label="{{i18n.menu}}">
      <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.6" stroke-linecap="round" aria-hidden="true"><path d="M3 6h18M3 12h18M3 18h18"/></svg>
    </button>
  </div>
</div>

Vakio-HTML:ssä kauppa vaihtaa logon itse. Omassa mallissa molemmat kuvat ovat HTML:ssä, ja CSS valitsee juuren tilan perusteella:

[data-bs-header-inner] { display: flex; align-items: center; justify-content: space-between; }
[data-bs-header-icons] { display: flex; align-items: center; }
.logo-light { display: none; }
[data-bs-transparent]:not([data-bs-scrolled]) .logo-dark { display: none; }
[data-bs-transparent]:not([data-bs-scrolled]) .logo-light { display: inline; }

#Valikkopaneeli omana HTML:nä

Kauppa piirtää paneelin juuren [data-bs-menu] ja avaa sen open-menu-actionilla. Malli käy läpi valikon linkit kohdasta Menu panel › Links, isot alakategorioineen ja sitten pienet:

<nav aria-label="{{i18n.menu}}">
  <ul>
    {{#each menu.links}}
    <li>
      <a href="{{this.href}}">{{this.label}}</a>
      {{#if this.children}}
      <ul>{{#each this.children}}<li><a href="{{this.href}}">{{this.label}}</a></li>{{/each}}</ul>
      {{/if}}
    </li>
    {{/each}}
    {{#each menu.secondary}}<li><a href="{{this.href}}">{{this.label}}</a></li>{{/each}}
  </ul>
  {{#if contact.email}}<p data-bs-menu-contact><a href="mailto:{{contact.email}}">{{contact.email}}</a></p>{{/if}}
  <button type="button" data-bs-action="close-menu">{{i18n.close}}</button>
</nav>

open-search avaa kaupan hakukentän kerroksena ylätunnisteen ja paneelin päälle. Jos HTML:ssäsi on elementti [data-bs-search-slot], hakukenttä piirretään sen sisään. Oma hakulomake toimii myös:

<form action="/search" method="get" role="search">
  <input type="search" name="q" placeholder="{{i18n.searchPlaceholder}}" aria-label="{{i18n.search}}">
  <button type="submit">{{i18n.search}}</button>
</form>

#Tuotekortti omana HTML:nä

Kauppa piirtää kortin juuren [data-bs-card]. Malli on sen sisäosa. Painike saa tuotteensa attribuuteista.

<a href="{{product.href}}">
  <div data-bs-card-media>
    {{#if product.image}}<img src="{{product.image}}" alt="{{product.imageAlt}}" loading="lazy">{{/if}}
    {{#if product.badge}}<span class="badge">{{product.badge}}</span>{{/if}}
  </div>
  <div data-bs-card-body>
    <h3 data-bs-card-title>{{product.title}}</h3>
    <p data-bs-card-price>{{#if product.compareAtPrice}}<s>{{product.compareAtPrice}}</s> {{/if}}{{product.price}}</p>
  </div>
</a>
<button type="button" data-bs-action="add-to-cart" data-bs-product-id="{{product.id}}">Add to cart</button>