# Lekérdezési ciklus

> A lekérdezési ciklus beállításai: bejegyzés-, kifejezés-, felhasználó-, tömb- és API-lekérdezés, rendezés, lapozás, találat nélküli tartalom és hibaelhárítás.

A lekérdezési ciklussal (Query Loop) tartalmat kérdezel le az adatbázisból, és minden találatot ugyanazzal a kialakítással jelenítesz meg. A ciklus belsejében minden elem az aktuális találat adatait használhatja dinamikus adatként. Az első bevezető példát az **Első lépések** csoport „Lekérdezési ciklusok és dinamikus adatok” fejezete mutatja; itt a teljes beállításkészlet következik.

A lekérdezési ciklus a [Szakasz, Tároló, Blokk és Div](https://hub.hellowp.io/hu/plugins/bricks-child/elemek-szakasz-es-tarolo/) típusú elrendezéselemeken érhető el, továbbá a klasszikus Harmonika és Diavetítés elemen. A Térkép elemnek saját lekérdezési vezérlője van a dinamikus címekhez. A beágyazható Harmonika, Fülek és Diavetítés elemek saját gyermekismétlőt használnak, ezért náluk nincs teljes lekérdezési ciklus vezérlő.

## Mire használható?

Ezeket kérdezheted le:

- **Bejegyzések:** legfrissebb vagy kapcsolódó bejegyzések (bármelyik regisztrált, nyilvános bejegyzéstípus).
- **Kifejezések:** bejegyzés kategóriák, címkék, termékkategóriák és hasonlók.
- **Felhasználók:** blogszerzők, közösségi tagok, csapattagok.
- **API:** külső JSON API elemei.
- **Tömb:** PHP vagy JSON jellegű tömb elemei.

## Dinamikus adat beágyazott ciklusban

A dinamikus adat mindig az aktuális ciklus aktuális találatára vonatkozik. Beágyazott ciklusban a belső találat az aktuális találat a belső ciklus elemeinél. A `{term_name}` például egy külső Kifejezések ciklusban az aktuális kifejezést adja, de egy beágyazott Bejegyzések vagy Média ciklusban az aktuális találat már bejegyzés vagy melléklet, ezért ugyanaz a címke nem a külső kifejezést olvassa.

A Bricks nem ad szülőciklusra mutató szintaxist a kimeneti címkékhez. A szülő találathoz tartozó értékeket lehetőleg tartsd a belső cikluson kívül. A belső lekérdezés beállításai használhatnak dinamikus adatot, miközben a Bricks a beágyazott lekérdezést építi, de a belső ciklus tartalma a belső találatra oldódik fel. A szülő találat elérése a belső ciklus tartalmából egyéni PHP-t vagy egyéni dinamikus adatcímkét igényel.

## Fontos: HTML-megjegyzések

A Bricks lekérdezési ciklus a frontenden automatikusan HTML-megjegyzéseket generál, például `<!--brx-loop-start-abc123-->`. Ezek nélkül nem működik az AJAX-os lapozás, a lekérdezési szűrők, a továbbiak betöltése és a végtelen görgetés. Egyes teljesítményoptimalizáló bővítmények alapból minden HTML-megjegyzést eltávolítanak. Ilyenkor állítsd be, hogy a Bricks megjegyzései megmaradjanak.

## Lekérdezési ciklus létrehozása

1. Adj hozzá egy **Tároló** (vagy Blokk) elemet a vászonhoz.
2. Kapcsold be a **Lekérdezési ciklus** kapcsolót.
3. A kapcsoló alatt megjelenik a **Lekérdezés** vezérlő (végtelen jel ikon). Kattints rá, és add meg a lekérdezés paramétereit.

Ez a tároló lett az ismétlődő elem: minden benne lévő elem annyiszor ismétlődik, ahány találat van.

![A Lekérdezési ciklus kapcsoló és a Lekérdezés vezérlő a Blokk elem tartalom lapján](./kepek/dinamikus-tartalom-ciklus-bekapcsolva.webp)

*A Lekérdezési ciklus kapcsoló és a Lekérdezés vezérlő a Blokk elem tartalom lapján* (https://minta-bolt.hu/lekerdezes-teszt/?bricks=run)

A képen a **Lekérdezési ciklus** kapcsoló és a **Lekérdezés** vezérlő látszik, a Szerkezet panelen pedig a ciklus elem mellett a végtelen jel ikon.

## A Lekérdezés vezérlő

A vezérlő a **Típus** mezőben ezeket a beépített lekérdezéstípusokat kínálja: **Bejegyzések**, **Kifejezések**, **Felhasználók**, **API** és **Tömb**. Aktív WooCommerce esetén további, kosárhoz, pénztárhoz, rendeléshez és fiókhoz tartozó típusok is megjelennek (lásd a WooCommerce moduláris elemeknél).

![A Típus legördülő menü a Lekérdezés vezérlőben](./kepek/dinamikus-tartalom-lekerdezes-tipusok.webp)

*A Típus legördülő menü a Lekérdezés vezérlőben* (https://minta-bolt.hu/lekerdezes-teszt/?bricks=run)

A képen a **Típus** választó lista látszik: **Bejegyzések**, **Kifejezések**, **Felhasználók**, **API**, **Tömb**, majd a WooCommerce-típusok. A vezérlő beállításai a kiválasztott típus szerint változnak.

- **Bejegyzések:** WP_Query típusú lekérdezés. Ez az alapértelmezett, bejegyzések, oldalak, médiafájlok és egyedi bejegyzéstípusok ciklusához.
- **Kifejezések:** WP_Term_Query. Egy taxonómia kifejezésein mész végig, például az összes termékkategóriát listázhatod.
- **Felhasználók:** WP_User_Query. Az oldal felhasználóin mész végig, például a blogszerzőkön vagy a csapattagokon (ha felhasználóként vannak felvéve).
- **API:** külső API által visszaadott elemeket jelenít meg (lásd az „API-lekérdezések” fejezetet).
- **Tömb:** PHP vagy JSON jellegű tömbadat elemeit jeleníti meg (lásd lejjebb).

A vezérlő tetején két ikon van: a bal oldali a **Létrehozás (Globális lekérdezés)**, a jobb oldali a **Lekérdezéskezelő** megnyitása. Ezekről a „Globális lekérdezések és Lekérdezéskezelő” fejezet szól.

### ACF Repeater forrás

Az ACF Repeater lekérdezés az aktív bejegyzés vagy lekérdezési környezet sorait olvassa. Ha a repeater mező egy ACF beállítási oldalhoz tartozik, a sorokat arról az oldalról veszi. Tetszőleges forrásbejegyzés vagy oldal azonosítója nem adható meg. Több oldalon közös, ismétlődő adathoz rendeld a mezőt egy ACF beállítási oldalhoz. Egy másik bejegyzés vagy oldal soraihoz egyéni PHP, egyéni lekérdezés vagy dinamikus adatos megoldás kell, amely átadja az ACF forrásbejegyzés azonosítóját.

## Lekérdezésszerkesztő (PHP)

A **Lekérdezésszerkesztő (PHP)** kapcsolóval saját PHP-lekérdezést írhatsz a legnagyobb rugalmasságért. A kapcsoló bekapcsolása után megjelenik a szerkesztő.

PHP tömböt kell visszaadnod a használni kívánt WordPress-lekérdezési argumentumokkal (WP_Query paraméterek). A szerkesztő támogatja a dinamikus adatot, így például egy ACF mező is megadhatja a bejegyzéstípust vagy egy dátumot.

A Bricks aláírja a lekérdezésszerkesztő kódját. Ha az aláírás hiányzik vagy érvénytelen, a Bricks nem futtatja a kódot. A visszaadott tömb csak lekérdezési argumentumokat tartalmazzon: ne írj ki semmit (echo), és ne futtass idegen adatbázis-írást a szerkesztőben.

## Bejegyzések lekérdezése

| Beállítás | Mit csinál |
|---|---|
| **Bejegyzéstípus** | egy vagy több bejegyzéstípus (alapból Bejegyzés) |
| **Rendezés alapja** | azonosító, szerző, cím, közzététel vagy módosítás dátuma, hozzászólások száma, relevancia, menüsorrend, véletlen és további lehetőségek (alapból a közzététel dátuma). Több érték is megadható |
| **Sorrend** | Növekvő vagy Csökkenő (alapból csökkenő). Több érték is megadható |
| **Bejegyzések száma oldalanként** | az oldalanként mutatott bejegyzések száma (alapból a WordPress **Beállítások → Olvasás** oldalán megadott érték) |
| **Eltolás** | a kihagyott bejegyzések száma |
| **Kiemelt bejegyzések figyelmen kívül hagyása** | ha bekapcsolod, a kiemelt (sticky) bejegyzések nem kerülnek a lista elejére |
| **Lekérdezések egyesítésének letiltása** | kikapcsolja a Bricks automatikus egyesítését archívum- és keresőoldalakon. Általában a láblécben, fejlécben vagy nem fő lekérdezésű ciklusokban kapcsold be |
| **Gyermeke** | a megadott szülő azonosítójú bejegyzés gyermekeit adja (a `post_parent` paraméter) |
| **Bevonás** / **Kizárás** | egy vagy több bejegyzés bevonása vagy kizárása. Dinamikus adatot is támogat |
| **Szerzők felvétele** / **Szerzők kizárása** | bejegyzések szűrése szerző szerint. Kiválaszthatsz felhasználókat, vagy felhasználói azonosítót adó dinamikus címkét használhatsz |
| **Aktuális bejegyzés kizárása** | kihagyja a jelenlegi bejegyzést (hasznos „kapcsolódó bejegyzések” szakaszhoz) |
| **Kifejezések (Bevonás)** / **Kifejezések (Kizárás)** | egy vagy több kifejezéssel rendelkező bejegyzések bevonása vagy kizárása |
| **Taxonómiai lekérdezés** | egy vagy több taxonómiai feltétel a bejegyzések szűréséhez |
| **Meta-lekérdezés** | egy vagy több egyéni mezőre épülő feltétel |
| **Relation** | a taxonómiai vagy meta-feltételek kapcsolata: befoglaló (OR) vagy kizáró (AND) |
| **Fő lekérdezés** | archívum- vagy keresősablonban az egyik ciklust fő lekérdezésnek jelöli |

A **Fő lekérdezés** megakadályozza a 404-es hibát, amikor a látogató más oldalra lapoz. Több ciklust ne jelölj meg fő lekérdezésként ugyanazon az oldalon, mert csak az első számít. A **Lapozás** elem **Lekérdezés** mezőjében is ezt a ciklust add meg.

A **Teljesítmény** szakasz kapcsolói:

- **A sorok teljes számának kihagyása:** lapozás, találatszám és oldalszám nélküli ciklusnál javítja a teljesítményt.
- **Kikapcsolás update_post_meta_cache** és **Kikapcsolás update_post_term_cache:** akkor kapcsold be, ha a ciklus nem használ bejegyzésmetát, illetve osztályozási kifejezést.
- Véletlen mag élettartama (TTL): véletlen sorrendű ciklusnál megadható, hány percig marad ugyanaz a véletlen sorrend. 10 perc esetén a találatok a következő 10 percben ugyanazok, így nem fordulnak elő duplikált bejegyzések különböző oldalakon vagy végtelen görgetésnél. A 0 kikapcsolja.

### Egyedi dátummezők meta-lekérdezésben

A meta-lekérdezés az adatbázisban tárolt értéket hasonlítja össze, nem az ACF-mező formázott kimenetét. Egy ACF **Date Picker** mezőnél a mező nevét add meg meta kulcsként, kapcsos zárójel és `acf_` előtag nélkül. Az ACF a mezőt `Ymd` formátumban tárolja, függetlenül a megjelenítési formátumtól. A közelgő bejegyzésekhez például:

- Meta kulcs: `event_date`
- Meta érték: `{current_wp_date:Ymd}`
- Összehasonlítás: `>=`
- Típus: `NUMERIC`

UTC szerinti összehasonlításhoz a `{current_date:Ymd}` címkét használd. Az ACF **Date Time Picker** értéke `Y-m-d H:i:s` formátumban tárolódik: ilyenkor a `{current_wp_date:Y-m-d H:i:s}` érték és a `DATETIME` típus kell. Az ACF csoportban lévő mezők kulcsa általában a tárolt `szülő_gyermek` név.

### Többszörös rendezés

A **Rendezés alapja** és a **Sorrend** mező több szempontot is támogat, ezeket a Bricks sorban alkalmazza. Például rendezhetsz előbb név szerint csökkenően, majd azonosító szerint csökkenően. Példák:

- **Több szempont:** egy címtárban előbb a népszerűség (egyéni mező) szerint csökkenően, majd a hozzáadás dátuma szerint növekvően.
- **Meta-lekérdezéshez kötött sorrend:** a rendezés a meta-lekérdezés feltételeire is hivatkozhat, például előadás dátuma és ideje szerint.

Lapozásnál másodlagos szempontként mindig add meg az azonosítót, hogy ne ismétlődjenek eredmények a lapok között. Ha például 15 bejegyzésnek azonos az ára, és oldalanként 5-öt mutatsz, a csak ár szerinti rendezés duplikátumokat okozhat. Ezért rendezz ár szerint, majd azonosító szerint.

### Példa: legfrissebb bejegyzések

Négy legfrissebb bejegyzést listázunk a kiemelt képpel, címmel és kivonattal.

1. Adj hozzá egy tárolót, és kapcsold be a **Lekérdezési ciklus** kapcsolót.
2. Tegyél a tárolóba egy **Kép** elemet, és a dinamikus adatok legördülő menüből válaszd a kiemelt képet.
3. Tegyél a tárolóba egy másik tárolót egy **Címsor** és egy **Egyszerű szöveg** elemmel.
4. A címsorba írd be: `{post_title}`, a szövegbe: `{post_excerpt}`. (Használhatod a **Bejegyzés címe** és a **Bejegyzés kivonata** elemet is.)
5. A lekérdezésben állítsd a **Bejegyzések száma oldalanként** mezőt 4-re.

## Média lekérdezése

A **Bejegyzéstípus** mezőben a **Média** (attachment) típus is választható. Ilyenkor megjelenik a MIME-típus mező, alapból a képeket kéri. Más típusokat vesszővel elválasztva adhatsz meg, például `image/jpeg,image/png,image/gif`.

Egy bejegyzéshez csatolt képek lekérdezéséhez add meg a **Gyermeke** mezőben a bejegyzés azonosítóját. Dinamikusan az aktuális bejegyzés azonosítója: `{post_id}`.

### Példa: médiagaléria

1. Adj hozzá egy tárolót, benne egy blokkot, abban pedig egy **Kép** elemet.
2. A tárolónál állítsd a **Flex tördelése** értékét **Tördelés**-re, az irányt vízszintesre.
3. A blokkon kapcsold be a lekérdezési ciklust, válaszd a **Média** bejegyzéstípust, és add meg, hány képet kérsz (bejegyzések száma oldalanként). A blokk szélességét és magasságát állítsd például 300 képpontra.
4. A képnél a dinamikus adat `{post_id}` legyen. A lekérdezés a mellékleteket adja vissza, ezért a kép azonosítója a bejegyzés azonosítója.
5. A képnél az `object-fit` legyen `cover`, a magasság 300 képpont.

## WooCommerce termékek lekérdezése

Ha a **Bejegyzéstípus** **Termék**, megjelenik egy WooCommerce szakasz (csak aktív WooCommerce-nél). Példák:

- **Kiemelt termékek:** az utolsó 10 kiemelt termék a kezdőlapon.
- **Kapcsolódó termékek:** 4 kapcsolódó termék az egyoldalas terméksablonban.
- **Felülértékesítési termékek (upsell):** 3 termék az egyoldalas terméksablonban.

### WooCommerce v2 lekérdezési ciklusok

A moduláris Kosár, Pénztár és Fiókom elrendezésekhez külön lekérdezési ciklusok vannak: kosárkuponok, díjak, adók, rendelési tételek, rendelés végösszegei, rendelési letöltések, vásárlói jegyzetek, fiókrendelések, fiók rendelési műveletek, fiók letöltések és fiókcímek. Ezek használatához be kell kapcsolni a **Bricks → Beállítások → WooCommerce** oldalon a speciális moduláris elemeket.

## Kifejezések lekérdezése

| Beállítás | Mit csinál |
|---|---|
| **Taxonómiák** | egy vagy több lekérdezendő taxonómia (alapból nincs) |
| **Rendezés alapja** | azonosító, név, szülő, darabszám vagy a bevonási lista sorrendje |
| **Sorrend** | Növekvő (alapból) vagy Csökkenő |
| **Szám** | az oldalanként mutatott kifejezések száma. A Bricks alapból a WordPress **Olvasás** beállítását használja. A 0 az összes találatot megjeleníti |
| **Eltolás** | a kihagyott kifejezések száma |
| **Szülő** | a szülő kifejezés azonosítója, így a közvetlen gyermekeket kapod. A 0 csak a gyermekkel rendelkező kifejezéseket adja |
| **Gyermeke** | az összes leszármazott kifejezés (nem csak a közvetlen gyerekek) |
| **Gyermektelen** | csak a gyermek nélküli kifejezéseket adja (nem hierarchikus taxonómiánál nincs hatása) |
| **Lekérdezések egyesítésének letiltása** | kikapcsolja az automatikus egyesítést |
| **Kifejezések bevonása / kizárása** | kifejezések bevonása vagy kizárása |
| **Üresek megjelenítése** | a bejegyzés nélküli kifejezéseket is mutatja |
| **Meta-lekérdezés** és **Relation** | egyéni mezős feltételek |
| **Nincs találat** | szöveg, ami megjelenik, ha nincs találat |
| **Aktuális bejegyzés kifejezése** | csak az aktuális bejegyzéshez rendelt kifejezéseket adja. Csak egyoldalas bejegyzés környezetben használd |

A **Szülő** példája: ha a termékkategória-szerkezetben a 55-ös azonosító a Pólók, akkor a **Szülő** 55 megadása csak a közvetlen gyerekeit (például T-shirt) adja, a **Gyermeke** 55 pedig az összes leszármazottat (T-shirt és Tees).

### Példa: termékkategóriák

Termékkategóriák listáját építjük (kategóriakép és hivatkozás az archívumra).

1. Adj hozzá egy tárolót, és kapcsold be a lekérdezési ciklust.
2. A lekérdezés típusa legyen **Kifejezések**, a taxonómia **Termékkategóriák**.
3. A tárolóba tegyél egy **Egyszerű szöveg** elemet, tartalma `{term_name}`.
4. A tároló háttérképét a dinamikus adatok legördülő menüből a **Termékkategória képe** címkére állítsd.
5. A tároló HTML-címkéje legyen „a (link)”, a hivatkozás típusa **Dinamikus adatok**, értéke a kifejezés archívum URL-je (`{term_url}`).

A ciklusban a kifejezés azonosítóját, nevét, archívum-URL-jét, leírását és bármelyik metaértékét lekérheted.

## Felhasználók lekérdezése

| Beállítás | Mit csinál |
|---|---|
| **Szerepkörök** | egy vagy több felhasználói szerepkör (alapból bármelyik) |
| **Rendezés alapja** | azonosító, név, felhasználónév, becenév, belépési név, e-mail, regisztráció dátuma, bejegyzések száma vagy a bevonási lista sorrendje |
| **Sorrend** | Növekvő (alapból) vagy Csökkenő |
| **Szám** | az oldalanként mutatott felhasználók száma. Alapból a WordPress **Olvasás** beállítása. A -1 az összeset mutatja |
| **Eltolás** | a kihagyott felhasználók száma |
| **Aktuális bejegyzés szerzője** | az aktuális bejegyzés szerzőjét kérdezi le |
| **Lekérdezések egyesítésének letiltása** | kikapcsolja az automatikus egyesítést |
| **Meta-lekérdezés** és **Relation** | egyéni mezős feltételek |
| **Nincs találat** | szöveg, ami megjelenik, ha nincs találat |

### Példa: a blog szerzői

1. Adj hozzá egy tárolót, kapcsold be a lekérdezési ciklust, a típus legyen **Felhasználók**, a szerepkör **Author** (Szerző).
2. A tárolóba tegyél egy **Kép** és egy **Egyszerű szöveg** elemet.
3. A kép dinamikus adata legyen a profilképet tartalmazó ACF mező.
4. A szöveg tartalma legyen `{wp_user_display_name}`.

## Lapozás elem

A lapozás a lekérdezési ciklus megfelelő társa. A **Lapozás** elem a **WordPress** elemcsoportban található, és kapcsolni kell a lekérdezést futtató elemhez: a **Lapozás** elem szerkesztésekor a **Lekérdezés** mezőben válaszd ki. Tipp: adj beszédes nevet azoknak a tárolóknak, amelyeken lekérdezés fut, hogy könnyebb legyen felismerni őket.

## Továbbiak betöltése (gomb)

A végtelen görgetés automatikusan tölt be újabb találatokat görgetéskor. Bármelyik elemhez (általában a **Gomb** elemhez) „Továbbiak betöltése” funkciót is adhatsz, ha hozzáadsz egy ilyen kattintás-interakciót.

## Lekérdezés azonosító, szűrők és élő keresés

Minden lekérdezési ciklust a ciklus elemének azonosítója azonosít. A frontenden ez általában a hatkarakteres Bricks azonosító a `#brxe-` előtag nélkül. Ha az elem azonosítója `#brxe-abc123`, a lekérdezés azonosítója általában `abc123`. Ezt kell megadnod:

- a lekérdezési szűrő elemeknél,
- a **Lapozás** elemnél,
- AJAX-os lapozásnál, továbbiak betöltésénél és végtelen görgetésnél,
- szűrőt követő dinamikus címkéknél (például `{query_results_count_filter:abc123}`).

A szűrők és az élő keresés a bejegyzés-, kifejezés- és felhasználó-lekérdezéseket támogatja, az API és tömb ciklusokat nem. Részletek: „Lekérdezésszűrők és élő keresés”.

## Lekérdezési ciklus Harmonikában és Diavetítésben

A klasszikus **Harmonika** és **Diavetítés** elem is kérhet adatot a lekérdezési ciklussal. A Harmonikában a lekérdezés annyi elemet hoz létre, ahány találat van. A „mester” harmonikaelem címét, alcímét és tartalmát kell beállítanod, ez lesz a sablon a dinamikus elemekhez. A Diavetítésben ugyanígy: ha a lekérdezési ciklus be van kapcsolva, megjelenik a **Lekérdezés** vezérlő és egy diaelem, ami az összes dia sablonja.

## Bevonás és kizárás: dinamikus adat

A **Bevonás** és a **Kizárás** mező dinamikus címkékből is olvashat azonosítókat, nem csak kézzel kiválasztott bejegyzésekből. A szerzőmezők hasonlóan működnek:

| Mező | Melyik paraméterbe kerül |
|---|---|
| **Bevonás** | `post__in` |
| **Kizárás** | `post__not_in` |
| **Szerzők felvétele** | `author__in` |
| **Szerzők kizárása** | `author__not_in` |

A szerzőmezők a Bejegyzések lekérdezésnél érhetők el, ha a Lekérdezésszerkesztő (PHP) ki van kapcsolva. Használhatod őket kiválasztott szerzők bejegyzéseinek megjelenítésére vagy elrejtésére, illetve az aktuális felhasználóhoz vagy a bejegyzés szerzőjéhez igazított ciklushoz. A többi beállítás (meta-lekérdezés, taxonómiai lekérdezés) továbbra is használható.

Támogatott mezőtípusok:

- **WordPress:** a `{wp_user_id}` és az `{author_id}` a szerzőmezőkhöz.
- **ACF:** Relationship, Post Object, Gallery, User.
- **Meta Box:** Relationship, Post, Image Advanced, Image, Image Upload, Single Image, User.
- **JetEngine:** Relationship, Post, Gallery, Media.

A szerzőmezőknél a címkének egy vagy több felhasználói azonosítót kell visszaadnia: a natív felhasználói címkék, illetve az ACF és Meta Box User típusú mezői használhatók. Ha egyszerre van felvételi és kizárási szabály, a Bricks a kizárt szerzőket kiveszi a felvételi listából. Ha ezután nem marad szerző, a lekérdezés nem ad vissza bejegyzést.

Példák:

1. **ACF Relationship mező bejegyzéstípus szerint, a mező sorrendjében.** Ha a mező több bejegyzéstípusra mutat, a találatokat a „Book” típusra korlátozhatod, és a relationship mezőben megadott sorrendet megtarthatod (rendezés a bevonási lista sorrendje szerint).
2. **Meta Box Image Advanced mező diavetítéshez.** Válaszd a dinamikus mezőt, a bejegyzéstípus legyen **Média**, szükség esetén adj meg MIME-típust, hogy csak a megfelelő képtípusok szerepeljenek.
3. **ACF-galéria véletlen sorrendben.** A bejegyzéstípus legyen **Média** (szükség esetén MIME-típussal), a rendezés pedig **Véletlen**.

## Típus: API

Az **API** lekérdezéstípus külső JSON API által visszaadott tömbelemeket jelenít meg. Az API-kérést az **API-beállítások** ablakban állítod be (URL, metódus, engedélyezés, fejlécek, URL-paraméterek, kérés törzse, válasz elérési útja, gyorsítótár időtartama, lapozás). A ciklusban a `{query_api @key:'mezőnév'}` címkével jelenítheted meg az aktuális elem egy mezőjét. Az API-ciklus korlátai:

- nem támogatja a lekérdezési szűrőket,
- nem támogatja az élő keresést,
- a szokásos bejegyzés-, kifejezés- vagy felhasználó-vezérlők helyett saját API-beállítások ablakot használ.

A teljes beállítás az „API-lekérdezések” fejezetben található.

## Típus: Tömb

A **Tömb** lekérdezéstípussal bármelyik PHP- vagy JSON-tömbön végigmehetsz. Használható:

- API-válasz tömbjeinek megjelenítésére,
- több forrás adatainak egyesítésére (például bejegyzések és egyéni tömbök),
- egyéni függvények visszaadott értékeinek ciklusos megjelenítésére.

A beállítás után a ciklus úgy viselkedik, mint bármelyik Bricks lekérdezés: a szerkesztőben kialakíthatod az elemeket, dinamikus címkével éred el az értékeket, és a lapozás is használható. Támogatott: AJAX-os és nem AJAX-os lapozás, továbbiak betöltése, végtelen görgetés.

### Beágyazott tömbök API-válaszból

Ha az API-válasz beágyazott tömböt tartalmaz (például `cars: ['BMW', 'Mazda']`), használj beágyazott tömbciklust, és add meg a megfelelő útvonalat a tömbszerkesztőben.

### Egyéni PHP-tömb

Ha van egy egyéni PHP-függvényed, amely tömböt ad vissza, a ciklusban a `{echo:my_custom_array()}` címkével használhatod. A függvényt engedélyezni kell a `bricks/code/echo_function_names` kampóval.

```php
// A my_custom_array függvényt engedélyezni kell a bricks/code/echo_function_names kampóval
function my_custom_array() {
  return [
    ['name' => 'John', 'age' => 30],
    ['name' => 'Jane', 'age' => 25],
  ];
}
```

### ACF jelölőnégyzet-választások listaként

Az ACF Checkbox mező a kiválasztott opciókat tömbként adja vissza. Ezt a tömböt használhatod lekérdezési forrásként, így minden választás külön listaelem lesz, egyéni PHP nélkül. A minta nem csak az ACF Checkbox mezőre érvényes: bármelyik, egyszerű tömböt adó dinamikus címkét megadhatsz a tömbszerkesztőben. A Bricks minden tömbértékhez egy ciklusi elemet hoz létre, a ciklusban pedig a `{query_array}` az aktuális értéket adja.

Ha a `{acf_MEZŐ_NEVE}` címkét közvetlenül egy szövegmezőbe írod, a Bricks az összes kiválasztott opciót egy szöveggé fűzi vesszővel és szóközzel. Ennek az elválasztónak nincs beállítása a szerkesztőben, módosításához a `bricks/dynamic_data/text_separator` PHP-kampó kell. A tömbös megoldás megtartja minden választást külön ciklusi elemként, így szemantikus listát kapsz, és a választásokat külön stílusozhatod.

Mindkét listaszinthez **Div** elemet használj. A **Blokk** alapból `display: flex`, ami felülírja a `ul`, `ol` vagy `li` böngészőalapú megjelenítését, és eltüntetheti a listajeleket. A Div-nek nincs alapértelmezett elrendezési stílusa, így a szemantikus listaelemek megtartják a normál megjelenésüket.

1. Adj hozzá egy **Div** elemet a lista tárolójának. A HTML-címkéje legyen `ul` (vagy `ol`, ha a sorrend számít). A **Lekérdezési ciklus** ezen maradjon kikapcsolva.
2. Adj hozzá egy másik **Div** elemet a lista tárolóján belül, a HTML-címkéje legyen `li`.
3. Az `li` elemen kapcsold be a **Lekérdezési ciklus** kapcsolót. A **Lekérdezés** vezérlőben a **Típus** legyen **Tömb**, a tömbszerkesztőbe pedig írd be: `{acf_MEZŐ_NEVE}`. A `MEZŐ_NEVE` helyére a Checkbox mező neve kerül.
4. Az `li` elembe tegyél egy **Egyszerű szöveg** elemet, tartalma `{query_array}`.

A szülő `ul` vagy `ol` egyszer jelenik meg, az `li` pedig annyiszor ismétlődik, ahány opció ki van választva. Ha a mező például a „Breakfast included”, „Parking” és „Wi-Fi” opciókat tartalmazza, a megjelenő lista ez a három sor.

Az ACF mező **Return Format** beállítása határozza meg, mit kap a ciklus:

- **Label:** az opciók feliratait.
- **Value:** a tárolt értékeket.
- **Both (Array):** alapból a feliratokat. Ha a tárolt értékekre van szükséged, a tömbszerkesztőben használd a `{acf_MEZŐ_NEVE:value}` címkét. Ha a mező már Value visszatérési formátumú, a `:value` nem kell.

A szülő lista elem **Stílus** lapján állíthatod a lista egészére vonatkozó térközt és behúzást. A ciklusban ismétlődő `li` elem stílusa ugyanazt a tipográfiát, térközt, hátteret vagy szegélyt adja minden elemnek.

Beágyazott vagy asszociatív tömbökhöz a `{query_array @key:'kulcsnév'}` szintaxis való.

### A `{query_array}` címke

- `{query_array}`: az aktuális tömbérték (egyszerű szövegek listája).
- `{query_array @key:'age'}`: a tömbelem megadott kulcsának értéke.

Példák:

1. **Egyszerű lista:** a `['Apple', 'Banana', 'Cherry', 'Donut']` tömbnél a ciklusban a `{query_array}` megjeleníti a gyümölcs nevét.
2. **Asszociatív tömb:** a `[['name' => 'John', 'age' => 30], ['name' => 'Alan', 'age' => 25], ['name' => 'Pony', 'age' => 66]]` tömbnél a `{query_array @key:'name'}` és a `{query_array @key:'age'}` használható.
3. **Beágyazott tömb:** ha minden elem egy `cars` tömböt is tartalmaz, helyezz egy tömbciklust a szülő cikluson belülre. A beágyazott ciklus tömbszerkesztőjébe írd: `{query_array @key:'cars'}`, a ciklusban pedig a `{query_array}` kiírja az egyes autókat.

## Eredmények szűrése

Az eredmények szűrése funkcióval feltételek szerint szűrheted a ciklus találatait, miután a tömb lekérdezése lefutott, de még a megjelenítés előtt. Működése hasonló a `bricks/query/result` PHP-szűrőhöz. Támogatott ciklustípusok: Tömb és ACF Repeater. Arra való, hogy:

- eltávolítsd a felesleges vagy érvénytelen találatokat,
- megakadályozd a nem kívánt cikluselemek megjelenítését.

Példa: a fenti, nevekből és korokból álló tömbnél csak az 50 évnél fiatalabbakat szeretnéd megjeleníteni. Állítsd be a szűrőt így:

| Mező | Operátor | Érték |
|---|---|---|
| `{query_array @key:'age'}` | `<` | `50` |

A szűrő kizárja az utolsó elemet (Pony, 66 év), így csak John és Alan jelenik meg.

## Nincs találat

Minden lekérdezési ciklus megjeleníthet tartalmat, ha nincs találat. Lehetőségek:

- a **Nincs találat** szakasz **Szöveg** mezője rövid üzenethez,
- a **Sablon** mező, ahol egy találat nélküli sablont választhatsz.

A Bricks belsőleg akkor is feldolgozhatja a cikluselemeket, ha nincs találat, hogy a szükséges szkriptek, stílusok és felugró ablak tartalmak elő legyenek készítve. Ez nem jelenti azt, hogy a látogató kitalált tartalmat lát.

## Teljesítmény

Mindig a lehető legkisebb lekérdezést használd:

- Adj meg reális **Bejegyzések száma oldalanként**, **Szám** vagy elemszám értéket.
- Nagy adathalmazon kerüld a `-1` értéket.
- Másodlagos ciklusoknál kapcsold be a **Lekérdezések egyesítésének letiltása** kapcsolót.
- Használd **A sorok teljes számának kihagyása** kapcsolót, ha nincs szükséged lapozásra vagy teljes találatszámra.
- A bejegyzésmeta- vagy kifejezés-gyorsítótár frissítését csak akkor kapcsold ki, ha a ciklus nem használ ilyen adatot.
- Lapozásnál adj meg stabil másodlagos rendezést.
- A beágyazott ciklusokat tartsd kicsinek.

## Hibaelhárítás

**A ciklus rossz bejegyzéseket mutat egy archívumon.** Ellenőrizd, hogy a ciklusnak együtt kell-e működnie az aktuális archívum-lekérdezéssel. Az archívum fő listájánál kapcsold be a **Fő lekérdezés** kapcsolót, és ne tiltsd le a lekérdezések egyesítését. Az ezzel nem kapcsolatos ciklusoknál kapcsold be a **Lekérdezések egyesítésének letiltása** kapcsolót.

**A lapozás 404-es hibát ad egy archívumon.** Csak egy ciklus legyen fő archívum-/keresőlekérdezésként megjelölve, és a **Lapozás** elem ezt a ciklust célozza.

**A szűrők nem módosítják a ciklust.** Ellenőrizd a céllekérdezés azonosítóját minden szűrőelemen, és hogy a céllekérdezés bejegyzés-, kifejezés- vagy felhasználó-típusú.

**Az AJAX-os lapozás vagy a végtelen görgetés leállt.** Ellenőrizd, hogy egy optimalizáló bővítmény nem távolítja-e el a Bricks lekérdezési ciklus HTML-megjegyzéseit (`<!--brx-loop-start-abc123-->`). Ezek kötelező jelölők.

**A dinamikus adat az oldalt mutatja a cikluselem helyett.** Győződj meg arról, hogy a dinamikus címkét tartalmazó elem a ciklus elemén belül van, és hogy a címke támogatja az adott lekérdezéstípust.

## Fejlesztői kampók

A lekérdezési ciklushoz ezek a kampók tartoznak: `bricks/query/run`, `bricks/terms/query_vars`, `bricks/users/query_vars`, `bricks/posts/merge_query`, `bricks/posts/query_vars`, `bricks/query/loop_object`, `bricks/query/loop_object_id`, `bricks/query/loop_object_type`, `bricks/query/no_results_content`, `bricks/query/before_loop` (művelet), `bricks/query/after_loop` (művelet), `bricks/query/result`, `bricks/query/result_count`, `bricks/query/result_max_num_pages`, `bricks/query/init_loop_index`. Ahol nincs külön jelölve, szűrőről van szó.