Bolti űrlapok

A bolti űrlapok a bolthoz tartozó közzétett definíciók. A téma a @poltura/theme-sdk/forms modulon keresztül jeleníti meg őket. A definíció határozza meg a field type-okat, a lépéseket, a feltételeket és a sikeres beküldést jelző üzenetet. A téma kizárólag az űrlap kinézetéről dönt.

Űrlap megjelenítéseHivatkozás másolása

import { StoreForm } from '@poltura/theme-sdk/forms';

export function Contact() {
  return <StoreForm handle='contact' />;
}

A <StoreForm handle='contact' /> betölti a közzétett űrlapot, és megjeleníti a látható mezőit, a lépéseket, a captchát, a submit gombot és a sikeres beküldést jelző üzenetet. A propjai a megjelenést alakítják anélkül, hogy módosítanák a definíciót:

Egyedi layouthoz adj át gyermekelemeket. A FormField egyetlen mezőt rajzol ki a címkéjével, vezérlőjével, súgószövegével és hibaüzenetével együtt (semmit sem mutat, amíg egy feltétel elrejti), a SubmitButton pedig a submit gomb, amely többlépéses űrlapokon a következő lépésre ugrik:

import { FormField, StoreForm, SubmitButton } from '@poltura/theme-sdk/forms';

export function Quote() {
  return (
    <StoreForm handle='quote' layout='compact' appearance='muted'>
      <FormField id='name' />
      <FormField id='email' />
      <FormField id='attachments' />
      <SubmitButton>Request a quote</SubmitButton>
    </StoreForm>
  );
}

A FormField egy renderer függvényt is elfogad egyedi markup készítéséhez. Megtartja a validationt, a hibákat, valamint az aria-invalid és aria-describedby bindingokat. A FieldControl a platform beépített vezérlője, amelyet elhelyezhetsz benne:

import { FieldControl, FormField } from '@poltura/theme-sdk/forms';

export function FramedMessage() {
  return (
    <FormField id='message'>
      {(state) => (
        <div className='rounded border p-3'>
          <FieldControl
            field={state.field}
            value={state.value}
            error={state.error}
            onChange={state.setValue}
          />
        </div>
      )}
    </FormField>
  );
}

A teljesen saját markup készítéséhez két hook olvassa az állapotot egy StoreForm elemen belül. A useStoreForm() a teljes űrlapot adja vissza (állapot, értékek, hibák, aktuális lépés, submit, next, back), a useStoreFormField('email') pedig egyetlen mezőt ad vissza az értékével, hibájával, láthatóságával és setterével.

HírlevélHivatkozás másolása

A @poltura/theme-sdk/forms csomagban található NewsletterForm és NewsletterTrigger jeleníti meg a hírlevél-feliratkozást. A useNewsletter() lekérdezi, hogy a bolt fogad-e feliratkozásokat, meg kell-e erősíteni őket e-mailben, és milyen szövegezéssel kérje az adatokat. Egy láblécben a newsletter blokk (vagy egy saját szekcióban a <NewsletterForm layout='footer' />) jeleníti meg a láblécoszlopot. Minden hírlevélűrlap a bolt közzétett hírlevélűrlapját használja, és követi a boltszintű hírlevél-beállítást, így a hozzájárulási szöveg és a validation mindenhol azonos.

Kapcsolatfelvételi wrapperHivatkozás másolása

A @poltura/theme-sdk/forms csomag ContactForm komponense a <StoreForm handle='contact' /> elemet, vagyis a bolt közzétett kapcsolatfelvételi űrlapját jeleníti meg, szövegezési propokkal (formTitle, nameLabel, showName, showSubject, submitLabel és továbbiak) a téma saját szövegeihez. A platform beépített contact-form blokkja továbbadja a beállításait ennek a komponensnek.

A boltnak rendelkeznie kell egy contact handle-lel közzétett űrlappal. A webáruház soha nem hoz létre ilyet.

TémaszerkesztőHivatkozás másolása

A kereskedők bármelyik sablonhoz hozzáadhatnak egy Űrlap szekciót (store-form), és név alapján kiválaszthatnak egy közzétett űrlapot. Az űrlap felügyeli a saját mezőit, fordításait és kézbesítését. A szekció felel a megjelenésért. Ugyanaz az űrlap több helyen is használható.

Az automatikus megnyitás ki van kapcsolva a témaszerkesztőben és a pénztároldalakon. Ott a felugró ablak teszteléséhez használd az előnézet gombot. Az űrlapot megnyitó gombok továbbra is működnek. A felugró ablakok és panelek a viewporton belül görgethetők, a billentyűzetes fókuszt bent tartják, az Escape billentyűvel vagy a bezárás gombbal csukhatók be, és visszaadják a fókuszt a megnyitó gombra. Ugyanazon űrlap bezárása és újranyitása megőrzi, amit a vásárló beírt. Ha elnavigálsz az oldalról, vagy egy másik űrlapot nyitsz meg, a beírt tartalom törlődik. A beírt adatokból semmi sem mentődik a böngésző tárhelyére.

Űrlap hozzárendelése gombhozHivatkozás másolása

A témaszerkesztőben kattints egy hivatkozásra vagy gombra a vásznon, hogy kiválaszd a szekciót vagy blokkot, amelyhez tartozik, vagy válaszd ki a szekciófában. A hozzá tartozó linkbeállítás két lehetőséget kínál: Hivatkozás megnyitása és Űrlap megnyitása. Válassz ki egy közzétett űrlapot, egy felugró ablakot vagy egy jobb oldali panelt, valamint a szélességet. Az Űrlap előnézete gombbal kipróbálhatod a téma közzététele nélkül, a téma közzététele pedig élesíti a beállítást. Tartsd lenyomva az Alt (Macen Option) billentyűt, miközben a vászonra kattintasz, ha a kiválasztás helyett követni szeretnéd a hivatkozást. A vásznon lévő form controlok továbbra is használhatók maradnak.

Minden url és link beállítás, valamint minden hivatkozáslista-bejegyzés ugyanezt a választási lehetőséget kínálja. A kódban megírt gombok csak akkor szerkeszthetők a témaszerkesztőben, ha linkbeállítást olvasnak be. Ne rendelj form actionöket pénztár- vagy kosárba helyező gombokhoz.

import { FormTrigger, useFormActions } from '@poltura/theme-sdk/forms';
import { Link } from '@poltura/theme-sdk/routing';
import type { LinkValue } from '@poltura/theme-sdk/elements';

export function AskButton() {
  return (
    <FormTrigger handle='contact' display='drawer' width='standard'>
      Ask a question
    </FormTrigger>
  );
}

export function SettingLink({ link }: { link: LinkValue }) {
  return <Link href={link} className='underline' />;
}

export function QuoteButton() {
  const { openForm } = useFormActions();
  return (
    <button
      type='button'
      onClick={(event) => openForm({ handle: 'quote', display: 'drawer' }, event.currentTarget)}
    >
      Request a quote
    </button>
  );
}

A @poltura/theme-sdk/routing csomagból származó Link változtatás nélkül jeleníti meg a linkbeállítás értékét. Amikor a kereskedő az Űrlap megnyitása lehetőséget választotta, a tárolt href egy ellenőrzött #poltura-form?… művelet, és a megnyitása navigáció nélkül jeleníti meg az űrlapot az oldal felett. A hagyományos hivatkozások a szokásos módon navigálnak. A platform biztosítja a form providert, így a témának nem kell sajátot mountolnia.

Kezdeti renderelésHivatkozás másolása

A szerver előre betölti a kapcsolatfelvételi és hírlevélűrlapokat, valamint minden olyan űrlapot, amelyet egy látható store-form szekció vagy a téma bármely linkbeállítása megnevez (legfeljebb 32 különböző űrlapot). Az elsőként visszaadott markup így már tartalmazza az űrlapot a „Loading form” felirat helyett. A FormTrigger szintén elkezdi betölteni a hozzá tartozó űrlapot, amint fókuszt kap, vagy a kurzor fölé ér. Ha egy handle csak a kódban szerepel, igény szerint töltődik be. Hívd meg a useFormActions().preloadForm(handle) metódust a korai betöltés indításához, vagy tedd elérhetővé egy linkbeállításon keresztül, hogy a szerver betöltse. Csak közzétett űrlapok töltődnek be így, piszkozat soha.

FájlokHivatkozás másolása

A FormField és a FieldControl automatikusan kezeli a fájlmezőket. Ha a téma saját fájlvezérlőt jelenít meg, a useStoreForm().uploadFiles(fieldId, files) metódust hívja meg, és a kiválasztott fájlokat a useStoreForm().files propból olvassa ki. A feltöltések a webáruházon keresztül zajlanak, és a beküldött érték feltöltési azonosítókat tartalmaz, soha nem fájl-URL-eket.

A témaszerkesztő előnézetében a kiválasztott fájlok a böngészőben maradnak, és nem töltődnek fel. Az előnézeti beküldés előnézetként fut le, nem tartalmaz fájlokat, és nem tárolódik.

Honnan származnak a definíciók?Hivatkozás másolása

A témakód soha nem definiálja az űrlap mezőit. A kereskedők az adminfelület Űrlapok oldalán hozzák létre és szerkesztik az űrlapokat, a webáruház pedig kizárólag azt olvassa be, amit közzétesznek.

CaptchaHivatkozás másolása

Minden közzétett űrlap saját captcha-beállítással rendelkezik, amely aktív, hacsak a kereskedő ki nem kapcsolta az adminfelület Űrlapok > Megjelenés menüpontjában, és közzé nem tette az űrlapot. A szerver érvényesíti a közzétett beállítást, függetlenül attól, hogy mit küld a böngésző. A StoreForm maga rajzolja ki a captchát.

Következő lépésekHivatkozás másolása

• Témaeszközök és média: képek és betűtípusok mellékelése a témához.
• forms referencia: a @poltura/theme-sdk/forms összes exportja.