Flow JavaScript API WordPress-űrlapokhoz

A Flow böngészőbeli futásidejű felülete a globális WP Suite-objektum alatt érhető el:

• globalThis.WpSuite.plugins.flow
• globalThis.WpSuite.plugins.flow.features

Készenléti segédek​

A többi WP Suite-bővítményhez hasonlóan a Flow is támogat futásidejű készenléti segédeket, például:

• onReady(cb)
• availability()

Az oldalon kibocsátott készenléti és hibaeseményeket is figyelheti:

• wpsuite:flow:ready
• wpsuite:flow:error

Példa:

window.addEventListener("wpsuite:flow:ready", () => {
	const flow = globalThis.WpSuite?.plugins?.flow;
	console.log("Flow is ready", flow?.status);
});

window.addEventListener("wpsuite:flow:error", (event) => {
	console.error("Flow failed to initialize", event.detail);
});

Hozzáférés a tárhoz​

A Flow egy késleltetve létrehozott tárat tesz elérhetővé itt:

• WpSuite.plugins.flow.features.store

Ez olyan haladó integrációknál hasznos, amelyeknek hozzá kell férniük a Flow futásidejű állapotához vagy konfigurációjához.

Modális API​

A Flow light DOM-alapú modális vezérlőt is elérhetővé tesz a WpSuite.plugins.flow.modals alatt.

Elérhető metódusok:

• register(modalElement, options?)
• unregister(modalOrId)
• open(modalId, options?)
• close(modalId, returnValue?)
• toggle(modalId, options?)
• closeAll(returnValue?)
• isOpen(modalId)
• get(modalId)
• registerAction(actionName, handler)
• unregisterAction(actionName)

Támogatott életciklusesemények:

• wps-flow-modal:before-open
• wps-flow-modal:open
• wps-flow-modal:before-close
• wps-flow-modal:close
• wps-flow-modal:ok
• wps-flow-modal:cancel
• wps-flow-modal:dismiss
• wps-flow-modal:error

A registerAction(actionName, handler) metódussal regisztrált műveletkezelők aszinkronok is lehetnek. A Modal futtatókörnyezete megvárja a visszaadott Promise teljesülését, várakozás közben nyitva és foglalt állapotban tartja a párbeszédablakot, letiltja a szabványos párbeszédablak-műveletek indítóit, az éppen futó indítóelemet pedig data-wps-flow-pending="true" és aria-busy="true" attribútummal jelöli. Ez a függő állapotjelölő szándékosan általános, így az alapvető Gomb blokkokkal és egyéni gombjelöléssel is működik.

Ha egy aszinkron kezelő false értéket ad vissza, az automatikus bezárás kimarad, és a párbeszédablak nyitva marad. Az elvetésszerű bezárási útvonalaknál, például a beépített bezárógombnál, a háttérre kattintásnál, az Escape használatánál vagy a programozott bezárási hívásoknál a futtatókörnyezet wps-flow-modal:dismiss eseményt is kibocsát.

Példa: nyisson meg egy Flow Modal blokkot egy szomszédos Gutenberg-gombbal, zárja be a Modal blokkon belüli másik Gutenberg-gombbal, és figyelje a bezárási eseményt:

1. A Flow Modal blokk felügyelőjében állítsa a modalId értékét newsletter-preferences értékre.
2. Adjon egy alapvető Gomb blokkot a Modal blokk mellé, és állítsa az Advanced -> Additional CSS class(es) értékét wps-flow-modal-open--newsletter-preferences értékre.
3. Adjon egy másik alapvető Gomb blokkot a modális tartalomba, és állítsa az Advanced -> Additional CSS class(es) értékét wps-flow-modal-close értékre.
4. Figyelje a wps-flow-modal:close eseményt a document objektumon.

A WordPress ezeket az egyéni osztályokat a megjelenített .wp-block-button burkolóra alkalmazza, ezért a futtatókörnyezet a belső hivatkozásra vagy gombra kattintást visszavezeti erre a burkolóra.

<!-- Neighboring core/button block -->
<div class="wp-block-button wps-flow-modal-open--newsletter-preferences">
	<a class="wp-block-button__link wp-element-button">
		Open preferences
	</a>
</div>

<!-- Inside the Flow Modal block -->

<div class="wp-block-button wps-flow-modal-close">
	<a class="wp-block-button__link wp-element-button">
		Close popup
	</a>
</div>

<script>
	document.addEventListener("wps-flow-modal:close", (event) => {
		const detail = event.detail ?? {};

		if (detail.modalId !== "newsletter-preferences") {
			return;
		}

		console.log("Flow modal closed", {
			modalId: detail.modalId,
			returnValue: detail.returnValue,
		});

		// Example: reset host-page UI or fire analytics here.
	});
</script>

Egy alapvető Gomb blokknál rendszerint a CSS-osztályos útvonal a legegyszerűbb integráció, mert a futtatókörnyezet már kezeli a .wps-flow-modal-open--{modalId} és .wps-flow-modal-close kattintásait. Egy .wps-flow-modal-close gomb bezárja a legközelebbi Flow Modal blokkot, és wps-flow-modal:close eseményt bocsát ki detail.returnValue === "close" értékkel.

Modális környezetet figyelembe vevő galériamegnyitók​

A wps-flow-modal:open tartalmazza a párbeszédablakot megnyitó triggerElement elemet, és a WpSuite.plugins.flow.modals.open(modalId, { triggerElement }) ugyanezt a bemenetet fogadja programozott megnyitáskor. A Flow Galéria blokk ebből a megnyitóelemből oldja fel az alábbi választható jelzéseket:

• wps-flow-gallery-target--{galleryId} or data-wps-flow-gallery-target="{galleryId}"
• wps-flow-gallery-index--N or data-wps-flow-gallery-index="N"

Így egy szomszédos alapvető Kép vagy Gomb blokk megnyithat egy párbeszédablakot közvetlenül egy adott galériaképnél. Ha a párbeszédablak csak egy Flow Galériát tartalmaz, a céljelzés elhagyható, és az index önmagában elegendő.

<div class="wp-block-image wps-flow-modal-open--product-lightbox wps-flow-gallery-target--product-gallery wps-flow-gallery-index--2">
	<figure class="wp-block-image size-large">
		<img src="/images/product-side.jpg" alt="Product side view" />
	</figure>
</div>

const triggerElement = document.querySelector(".hero-product-image");

globalThis.WpSuite.plugins.flow.modals.open("product-lightbox", {
	triggerElement,
});

Űrlapra korlátozott mezőalapértékek​

A Flow mag segédmetódusokat is elérhetővé tesz a WpSuite.plugins.flow alatt az űrlapra korlátozott mezőalapértékekhez:

• setFormFieldDefaultValue(formId, fieldName, value)
• setFormFieldDefaultValues(formId, values)
• clearFormFieldDefaultValues(formId)
• getFormFieldDefaultValue(formId, fieldName)
• getFormFieldDefaultValues(formId)

Minden segéd Promise értéket ad vissza, mert a Flow az értékek olvasása vagy írása előtt megvárja belső tárát.

Példa:

await globalThis.WpSuite.plugins.flow.setFormFieldDefaultValues("newsletter-footer", {
	email: "user@example.com",
	utm_source: "spring-campaign",
});

Ha közvetlenül a tárral szeretne dolgozni, használja ugyanezeket a műveleteket a features.store és wp.data.dispatch(...) segítségével:

const store = await globalThis.WpSuite.plugins.flow.features.store;
const actions = globalThis.wp.data.dispatch(store);

actions.setFormFieldDefaultValue("newsletter-footer", "email", "user@example.com");

Ezek az API-k űrlapra korlátozott alapértékeket írnak a megosztott Flow-tárba. A megjelenített Flow-űrlapok formId alapján oldják fel és alkalmazzák ezeket az alapértékeket.

Futásidejű karakterlánc-interpoláció​

A Flow egyes futásidejű karakterlánc-beállításai támogatják a tokeninterpolációt. Ez azt jelenti, hogy a Flow a karakterlánc használata előtt az aktuális oldal környezetéből származó értékekre cseréli a {{...}} helyőrzőket.

Ez például űrlaponkénti endpointPath vagy API-alapú választómező apiEndpoint beállításánál hasznos, ha a végleges URL az aktuális oldaltól, lekérdezési karakterlánctól, gazdaoldali globális értékektől vagy az aktuális űrlapértékektől függ.

Az API-alapú választómezők az egyes válaszelemekből is meghatározhatják a kezdeti kijelölési állapotot. Az elemenkénti jelző vagy állapotmező olvasásához használja az apiSelectedPath értéket, választhatóan pedig az apiSelectedValue értéket, ha az elem csak egy adott, például SUBSCRIBED értéknél számít kijelöltnek. Ez különösen checkbox-group esetén hasznos, de a select, radio és tags mezőkre is érvényes.

Egyéni űrlapbeküldésnél a végpont-URL GET, POST, PUT vagy PATCH értékű endpointMethod beállítással párosítható. Ha nincs beállított metódus, a Flow POST kérést használ. GET esetén a sorosított mezőértékeket JSON-kéréstörzs helyett URL-lekérdezési paraméterekként küldi. További böngészőoldali kérésfejléceket is csatolhat az endpointHeaders segítségével, amely a blokkattribútumokban JSON-objektumot tartalmazó karakterláncként tárolódik; a Flow ezeket egyesíti a meglévő reCAPTCHA-kérésfejléccel, ha van ilyen. A fejlécértékek ugyanazokat a futásidejű interpolációs tokeneket támogatják, mint az endpointPath, de URL-kódolt útvonalszakaszok helyett egyszerű karakterláncként oldódnak fel.

Ha az endpointPath vagy egy API-alapú mező apiEndpoint értéke futásidejű tokeneket használ, a Flow URL-kódolja a dinamikus mező- és lekérdezésitoken-értékeket, mielőtt beilleszti őket a végleges URL-be.

Támogatott tokencsaládok:

• {{email}}, {{fullName}}, {{message}} stb. az aktuális űrlap mezőnév szerinti értékeihez
• {{query.foo}} — lekérdezésikarakterlánc-értékek a window.location.search alapján
• {{location.href}}, {{location.origin}}, {{location.pathname}}, {{location.search}}, {{location.hash}}, etc.
• {{wp.postId}}, {{wp.postSlug}}, {{wp.postType}}, {{wp.postTitle}}, {{wp.postUrl}}
• {{wpsuite.apiBaseUrl}}, {{wpsuite.siteSettings.siteId}} stb. a globális WpSuite.* objektum rövidítéseként
• {{global.MyApp.config.formsBaseUrl}} bármely más, a globalThis objektumon elérhető primitív értékhez
• {{field.email}}, {{field.fullName}} stb. az aktuális űrlapmezőértékek kifejezett álneveként

Példák:

{{location.origin}}/contact
https://api.example.com/forms?source={{location.pathname}}
{{wpsuite.apiBaseUrl}}/contact
{{global.MyApp.forms.submitUrl}}
{{wpsuite.contactApiBaseUrl}}/{{email}}

Fontos korlátok:

• Az interpoláció nem tetszőleges JavaScript-végrehajtás. Csak ismert futásidejű környezetekből vagy a globalThis tulajdonságútvonalaiból olvas értékeket.
• A függvényhívások, kifejezések és feltételek, például foo ? bar : baz, nem támogatottak.
• A global.* és wpsuite.* esetén az értéknek primitívként (string, number vagy boolean) már léteznie kell az oldalon, amikor a Flow feloldja a beállítást.
• Az aktuális űrlapmezők értéktokenjei csak olyan futásidejű felületeken érhetők el, amelyek már hozzáférnek az űrlapállapothoz, például a megjelenített űrlapmezőkben és az API-alapú választásbetöltőkben.

Képesség eldöntése​

Csomagolt integrációkban a Flow magmodulja olyan segédfüggvényeket is elérhetővé tesz, mint a waitForFlowReady(), getStore(), decideCapability() és resolveBackend(). Ezek az inicializálás megvárásakor vagy annak eldöntésekor hasznosak, hogy az aktuális webhely használhat-e háttérrendszert figyelembe vevő funkciókat.

Futásidejű űrlapesemények​

A megjelenített Flow-űrlapok buborékoló CustomEvent eseményeket bocsátanak ki a fontos futásidejű műveletekhez. Az űrlap gazdaelemén vagy document szinten figyelheti őket, mert az események buborékolnak és átlépik az árnyékhatárt.

document.addEventListener("smartcloud-flow:submit-success", (event) => {
	console.log("Flow submit success", event.detail);
});

document.addEventListener("smartcloud-flow:wizard-step-change", (event) => {
	console.log("Wizard moved", event.detail);
});

A jelenlegi események:

• smartcloud-flow:draft-saved
• smartcloud-flow:draft-loaded
• smartcloud-flow:draft-deleted
• smartcloud-flow:ai-suggestion-accepted
• smartcloud-flow:ai-suggestions-rejected
• smartcloud-flow:submit-after-ai-accepted
• smartcloud-flow:submit-success
• smartcloud-flow:success-state-shown
• smartcloud-flow:wizard-step-change
• smartcloud-flow:return-to-form
• smartcloud-flow:options-request-error
• smartcloud-flow:error

Minden konkrét esemény általános smartcloud-flow:state-change eseményt is kibocsát, amelynek detail.event mezője az eredeti eseménynevet tartalmazza.

Gyakori detail mezők:

• formId
• action
• submissionId
• status
• suggestionId
• varázsló-metaadatok, például wizardPath, stepIndex, stepTitle és totalVisibleSteps

API-alapú mezők betöltési hibáinál a detail a fieldName, fieldType, requestMethod, errorType, message, status és responseText mezőt is tartalmazhatja.

Példa: API-alapú választási hiba kezelése a gazdaoldal JavaScriptjéből:

<div id="preferences-api-error" hidden></div>

<script>
	const errorBox = document.getElementById("preferences-api-error");

	document.addEventListener("smartcloud-flow:options-request-error", (event) => {
		const detail = event.detail ?? {};

		if (detail.formId && detail.formId !== "preferences-form") {
			return;
		}

		const message =
			typeof detail.message === "string" && detail.message.trim()
				? detail.message.trim()
				: "Unable to load options right now.";

		if (errorBox) {
			errorBox.textContent = message;
			errorBox.hidden = false;
		}

		console.warn("Flow options request error", {
			formId: detail.formId,
			fieldName: detail.fieldName,
			status: detail.status,
			errorType: detail.errorType,
			responseText: detail.responseText,
		});
	});

	document.addEventListener("smartcloud-flow:submit-success", () => {
		if (errorBox) {
			errorBox.hidden = true;
			errorBox.textContent = "";
		}
	});
</script>

A felhasználói felületen a detail.message értéket használja. A detail.responseText értéket diagnosztikai vagy hibakeresési adatként kezelje, ne jelenítse meg közvetlenül a végfelhasználóknak.

Ez az eseményréteg az ajánlott integrációs pont, ha egy külső alkalmazásnak analitikára, konverziókövetésre, egyéni átirányításokra vagy gazdaoldali felületreakciókra van szüksége.