# Async Listing

> Aszinkron listázás: JSON-adatok betöltése a böngészőben, adatforrások, az API Data jelölő, eredmény-kiegészítés és szűrőkompatibilitás.

Az **Async Listing** a listázás olyan formája, amelyben a szerver nem rendereli ki egyenként a listaelemeket. Az oldal betöltése után a böngésző JSON-adatot kér, és abból építi fel az elemeket. A listázási sablon készítése ugyanolyan marad, de a szerver erőforrásait az adatok lekérésére használja, nem a megjelenítésre. Elementorban, a blokkszerkesztőben, Bricksben és Timber/Twig nézetben is elérhető.

## Mikor érdemes használni

- REST API végpontokról származó adatok megjelenítése kevés szerverterheléssel (a JetEngine REST API-listázások végpontjaival a szerver szinte alig renderel).
- Belső Lekérdezéskészítő-lekérdezések eredményének megjelenítése úgy, ahogy vannak. Ilyenkor az **Results Mutation** a hiányzó adatokat (képek, hivatkozások) pótolhatja.
- Haladó lekérdezőeszközök (például Gato GraphQL) adatainak megjelenítése.

Ne használd, ha:

- a listázás nagyban épít a hagyományos, szerveroldali dinamikus címkékre, visszahívásokra és makrókra;
- az első betöltéskor az összes listaelem teljes HTML-jére szükség van;
- a listázáshoz JetSmartFilters szűrő kell, és az adatforrás nem JetEngine-lekérdezés.

## Bekapcsolás és használat

1. A **JetEngine → JetEngine → Modulok** fülön kapcsold be az **Async Listing** modult, és kattints a **Mentés** gombra.
2. Készíts vagy szerkessz listázási sablont Elementorban, blokkszerkesztőben, Bricksben vagy Timber/Twig nézetben.
3. A sablon azon elemeihez, ahol a JSON-válasz értékét akarod kiírni, add meg az **API Data** jelölőt. Szerkesztőnként így érheted el:
   - Elementor: az **API Data** dinamikus címke.
   - Blokkszerkesztő: az **API Data** forrás a dinamikus tartalomnál.
   - Bricks: az **API Data** token a JET ENGINE DYNAMIC DATA részben.
   - Timber/Twig: az **API Data** a dinamikus adat gombban, vagy az `api_data()` függvény.
4. A JetEngine saját listaelem-widgetjei (Dynamic Field, Dynamic Image, Dynamic Link) is használhatják az **API Data** forrást.
5. Az oldalon a szokásos Listing Grid helyett az **Async Listing** elemet használd, válaszd ki a sablont és az adatforrást.

Példa a leképezésre:

```
cím > post_title
alcím > author.name
kép URL > image.url
gomb hivatkozás > permalink
```

Az **API Data** egy jelölő (token), nem a tényleges érték: a listázás megjelenítésekor cserélődik ki. Ezért a Dynamic Field visszahívásai és a környezetet váltó beállítások nem alkalmazhatók rá.

## A widget beállításai

Az Elementor-widget négy fület ad: **Template**, **Data Source**, **Layout** és **States**. A **Results Mutation** fül akkor jelenik meg, ha az adatforrás **JetEngine Query** vagy **JetEngine REST API Endpoint**. A blokkszerkesztőben és Bricksben ugyanezek a beállítások vannak.

### Template

Itt választod ki a listázási elemet.

### Data Source

| Forrás | Mit csinál |
|---|---|
| **JetEngine Query** | A Lekérdezéskészítőben létrehozott lekérdezés adatait kéri le. |
| **WP REST API** | WordPress REST API-végpont. A **REST Path** a végpont útvonala (például `wp/v2/posts`), csak ugyanazon a webhelyen lévő útvonal adható meg, teljes URL nem. Az **Items Path** a tételek tömbjének útvonala a válaszban (például `data.items`); hagyd üresen, ha maga a válasz a tömb. JetSmartFilters nem támogatott. |
| **Gato GraphQL Query** | A Gato GraphQL bővítménnyel készített lekérdezés. Ha a bővítmény nem aktív, az opció **Unavailable**. JetSmartFilters nem támogatott. Beállításai: **Persisted Query** (előre elmentett lekérdezés), **Items Path** (a tételek tömbje, például `data.posts`), **Query Args** (argumentumok **Key** és **Value** párokkal, az **Add Item** gombbal bővíthetők). |
| **JetEngine REST API Endpoint** | A JetEngine REST API-listázások funkciójával létrehozott végpont. |

### Results Mutation

Itt a „nyers” eredményt egészítheted ki olyan adatokkal, amelyek nincsenek benne: metamezőkkel, kiemelt képpel stb. Tipikus felhasználás:

- bejegyzés-hivatkozás hozzáadása azonosító alapján;
- kiemelt kép URL-je bejegyzésazonosító alapján;
- a metamezőből jövő csatolmányazonosító képhivatkozássá alakítása;
- kifejezésazonosítók kiegészítése névvel, slug-gal, leírással, számmal vagy hivatkozással;
- felhasználóazonosítók kiegészítése megjelenő névvel, nicename-mel, szerzői archívum URL-jével, avatar URL-jével;
- kiválasztott metaértékek hozzáadása bejegyzésekhez, kifejezésekhez, felhasználókhoz, hozzászólásokhoz;
- egyéni WordPress-szűrő alkalmazása.

Ez adatgazdagító réteg, nem teljes átalakítás: néhány további mezőt ad a meglévő eredményhez, nem változtatja az elemek számát, nem kezeli a frontend logikát, nem futtat tetszőleges kódot, és nem közvetlen adatforrásokat dolgoz fel.

A **Mutate Results** kapcsolóval kapcsolod be, az **Add Item** gombbal adsz hozzá lépést. A lépés **Method** értéke:

| Módszer | Beállításai |
|---|---|
| **Inject Meta Value** | **Object Type** (**Post**, **Term**, **User**, **Comment**), **Get Object ID From Prop** (melyik tulajdonság tartalmazza az azonosítót), **Meta Field** (a lekérendő kulcs, például `thumbnail_id`), **Inject Into Prop** (ebbe a tulajdonságba kerül az érték). |
| **Inject Post URL By ID** | **Inject Into Prop**, **Get From Prop** (a bejegyzésazonosítót tartalmazó tulajdonság). |
| **Get Image By ID** | **Inject Into Prop**, **Get From Prop**, **Image Size** (például **Full**). |
| **Inject Featured Image** | **Inject Into Prop**, **Image Size**. |
| **Apply WP Filter** | **Filter Suffix**: a WordPress-szűrő nevéhez fűzött utótag (például `custom-transform`). |
| **Inject Term Data** | **Inject Into Prop**, **Get Term ID From Prop** (például `term_id`), **Taxonomy**, **Return Field** (például `name`). |
| **Inject User Data** | **Inject Into Prop**, **Get User ID From Prop**, **Return Field** (például `display_name`). |

### Layout

Az elrendezés előbeállítása: **Grid**, **Slider**, **Masonry** vagy **Scroll**. Törésponthoz állítható az oszlopok száma és a térköz, valamint az elemek magassága, a HTML-címkék és a CSS-osztályok.

### States

A betöltés, az üres és a hibaállapot megjelenítését, szövegét és láthatóságát állíthatod itt.

## Hogyan működik a frontenden

1. Az oldal az Async Listing burkolóját és a futtatási beállításokat adja ki, a listaelemek nincsenek előrerenderelve a HTML-ben.
2. A frontend lekéri a JSON-adatot.
3. A böngésző megkapja az eredményt.
4. A böngésző lemásolja a listaelem-sablont, és az értékeket a szövegcsomópontokba és attribútumokba helyezi.

A sablon tehát a vizuális szerkezetet adja, a JSON-válasz az adatokat.

## Példák

### JetEngine Query forrás

1. Hozz létre egy egyéni bejegyzéstípust, egy lekérdezést hozzá és egy listázási sablont, amelynek a forrása a bejegyzéstípus.
2. A sablonban a Dynamic Field, a Dynamic Link és a Dynamic Image widgetnél válaszd az **API Data** forrást, és írd be a mezők nevét (a példában `ID`, `post_title`, `url_prop`, `feature_img_prop`).
3. Egy új oldalon add hozzá az **Async Listing** widgetet, válaszd ki a sablont, a **JetEngine Query** forrást és a lekérdezést. Az azonosítók és a címek azonnal megjelennek.
4. A hivatkozás és a kiemelt kép pótlásához nyisd meg a **Results Mutation** részt, kapcsold be a **Mutate Results** kapcsolót, és kattints az **+ Add Item** gombra.
5. Az első lépés **Inject Post URL By ID**: az **Inject Into Prop** a hivatkozás tulajdonsága (`url_prop`), a **Get From Prop** az azonosító tulajdonsága (`ID`).
6. A második lépés **Inject Featured Image**: az **Inject Into Prop** a kép tulajdonsága, és válaszd ki az **Image Size** értékét.

### REST API forrás

1. Regisztrálj REST API-végpontot a kiszolgáló webhelyen (egyedi tartalomtípus-elemek távoli hozzáadásához használt végpont).
2. Készíts listázási sablont a végponthoz: a Dynamic Field és a Dynamic Image forrása **API Data**, a mezők a példában `_ID`, `name_api_cct`, `mediaurl`.
3. Az oldalon az **Async Listing** widgetben válaszd a sablont, a **JetEngine REST API Endpoint** forrást és a végpontot.

## Együttműködés a JetSmartFilters szűrőkkel

Teljes támogatás csak a **JetEngine Query** adatforrással van. Ez magában foglalja:

- az **AJAX**, a **Mixed** és a **Page Reload** szűrőtípusokat;
- a lapozás metaadatainak frissítését;
- az eredménykiegészítés megőrzését a szűrt folyamatban.

A többi forrás az első adathalmazt megjeleníti, de a JetSmartFilters nem módosítja a lekérdezésüket és eredményüket. Ez szándékos: a szűrhetőség az adott forrás képességeitől függ, például a WP REST API kevesebb szűrési paramétert ismer, mint a WP Query.

## Gyakori kérdések

**Milyen adatforrások használhatók?** JetEngine Lekérdezéskészítő, WP REST API, Gato GraphQL és JetEngine REST API-végpontok.

**Használhatok JetSmartFilters szűrőt?** Teljes mértékben csak a **JetEngine Query** forrással.

**Mi az API Data?** Helyettesítő jelölő a sablonban, amely az elemeket a JSON-válasz értékeihez rendeli.

**Mi a Results Mutation?** A visszaadott adatok kiegészítése további értékekkel: metamezők, bejegyzés-hivatkozások, kiemelt képek, kifejezés- és felhasználóadatok.

**Mikor érdemes használni?** API-k, Lekérdezéskészítő-lekérdezések és más haladó adatforrások megjelenítésére, kisebb szerveroldali renderelési terheléssel.

**Mikor kerüljem?** Ha a listázás erősen a hagyományos szerveroldali dinamikus címkékre, visszahívásokra, makrókra épít, vagy az első betöltéskor az összes elem HTML-jére szükség van.

**Megjeleníthetek képeket és hivatkozásokat?** Igen. Az **API Data** képhivatkozásokra, linkekre és más JSON-értékekre is használható, a hiányzó adatokat a **Results Mutation** pótolhatja.