A modern WordPress fejlesztés, különösen a Gutenberg blokkok világa elsőre ijesztő lehet. npm, build, src, webpack, React… rengeteg új fogalom és fájl, amik között könnyű elveszni. Olyan, mint egy profi séf konyhája: elsőre káosznak tűnik, de ha megértjük a rendszert, rájövünk, hogy mindennek megvan a maga helye és célja. Ha nem érted elsőre, ne aggódj – még a node_modules se tudja mindig, mi van benne.
Ebben a cikkben lépésről lépésre végigvezetlek egy komplett, minden igényt kielégítő Gutenberg blokk létrehozásán. Nem csak „Hello World” szintű példát nézünk, hanem egy valós, testreszabható és profi megoldást készítünk el közösen. A végére a káoszból rend lesz, és magabiztosan fogsz mozogni a blokkfejlesztés világában.
Na, vágjunk is bele!
Mit fogunk építeni?
Készítünk egy „Görgetés Animáció” blokkot. Ez egy egyszerű, de nagyszerű funkciót ad az oldalainkhoz: egy animált egér ikont jelenít meg, ami finoman jelzi a látogatónak, hogy görgessen lejjebb. Pontosan ilyen van a főoldalon is
Itt látható html/css-ben: https://codepen.io/deepakkv/pen/WwmjKQ
A blokk a Gutenberg szerkesztőben „Görgetés” szóra névre szűrve gyorsan megtalálható, egérrel a kívánt pozícióba húzható. A blokk egy különálló, React-alapú bővítmény része, így bármely WordPress (Gutenberg) oldalon használható.
És így fog kinézni:
Ez a blokk kifejezetten a felső, úgynevezett „hero” vagy banner szakaszban működik jól, mert lefelé görgetésre eltűnik – épp ez a célja!
Ha viszont a cikk közepe táján vagy a lábléc környékén helyeznéd el, akkor a görgetésre gyakorlatilag azonnal eltűnne – így teljesen értelmét veszíti.
A blokkunk a következőket fogja tudni:
- Görgetésre Halványulás: Amikor a látogató elkezd lefelé görgetni, az ikon finoman elhalványul és eltűnik.
- Testreszabható Szín: A szerkesztőben egy színválasztóval beállíthatjuk az ikon színét.
- Igazítás: A blokkot balra, középre vagy jobbra igazíthatjuk.
- Valós idejű Előnézet: A szerkesztőben pontosan azt látjuk, amit a látogatók is fognak.
Ez a kis projekt tökéletes példa arra, hogy bemutassuk a modern fejlesztési munkafolyamatot, a fájlok logikus szétválasztását, és a biztonságos kódolási gyakorlatokat.
A Plugin Neve és Fájlstruktúrája
A pluginünk neve legyen „Görgetés Animáció Blokk”. A végső, tiszta fájlszerkezetünk pedig így fog kinézni:
gorges-animacio-blokk/
│
├── gorges-animacio-blokk.php # A "PORTÁS": Bejelenti a plugint a WordPress-nek.
│
├── package.json # A "SZERSZÁMOSLÁDA": Leírja a fejlesztői eszközöket.
│
├── build/ # A "KÉSZ TERMÉK": A böngészőbarát, kész fájlok.
│
└── src/ # A "MŰHELY": Itt dolgozunk mi, a forrásfájlok helye.
│
├── block.json # A "SZEMÉLYI IGAZOLVÁNY": A blokk legfontosabb leírója.
│
├── index.js # A "SZERKESZTŐ AGYA": Kezeli a blokk admin oldali működését.
│
├── render.php # A "KIRAKAT MOTORJA": Legenerálja a HTML-t a látogatóknak.
│
├── style.scss # A "KIRAKAT FESTÉKE": A frontend oldali stílusok.
│
├── editor.scss # A "SZERKESZTŐ FESTÉKE": Az admin oldali stílusok.
│
└── scroll-fade.js # A "FRONTEND EFFEKT": A görgetésre elhalványulás logikája.Most pedig nézzük meg részletesen, hogy mit tartalmaznak ezek a fájlok!
1. A fő plugin fájl: gorges-animacio-blokk.php
Minden WordPress plugin ezzel a fájllal kezdődik. Ez a „portás”, aki üdvözli a WordPress-t, bemutatkozik a fejlécben található kommentekkel, és megmondja a rendszernek, hogy hol keresse a blokkunk tényleges definícióját (register_block_type).
gorges-animacio-blokk.php
<?php
/**
* Plugin Name: Görgetés Animáció Blokk
* Description: Egy egyedi Gutenberg blokk, amely egy lefelé görgető, animált egeret jelenít meg, aminek a színe és pozíciója állítható, és a görgetésre elhalványul.
* Requires at least: 6.0
* Requires PHP: 7.4
* Version: 1.3.0
* Author: Lőrincz András
* License: GPL-2.0-or-later
* License URI: https://www.gnu.org/licenses/gpl-2.0.html
* Text Domain: gorgetes-animacio-blokk
*/
declare(strict_types=1);
if ( ! defined( 'ABSPATH' ) ) {
exit; // Közvetlen hozzáférés tiltása
}
/**
* Regisztrálja a blokkot a block.json fájl alapján.
*/
function gorgetes_animacio_blokk_init(): void {
register_block_type( __DIR__ . '/build' );
}
add_action( 'init', 'gorgetes_animacio_blokk_init' );A lényeg: Rövid, tiszta, és csak a legszükségesebbet csinálja: elindítja a folyamatot.
2. A fejlesztői eszközök: package.json
Ez a fájl a mi „szerszámosládánk” leltára. Megmondja az npm-nek (Node Package Manager), hogy milyen fejlesztői eszközökre van szükségünk (itt a @wordpress/scripts), és milyen parancsokat használhatunk (build a végleges kód generálásához, start a folyamatos fejlesztéshez).
package.json
{
"name": "gorges-animacio-blokk",
"version": "1.3.0",
"description": "Egy Gutenberg blokk, amely egy lefelé görgető egér animációt jelenít meg.",
"author": "Lőrincz András",
"license": "GPL-2.0-or-later",
"main": "build/index.js",
"scripts": {
"build": "wp-scripts build src/index.js src/scroll-fade.js --output-path=build",
"start": "wp-scripts start src/index.js src/scroll-fade.js --output-path=build"
},
"devDependencies": {
"@wordpress/scripts": "^27.0.0"
}
}A lényeg: Ez a fájl a fejlesztést segíti, a kész, feltöltött plugin működéséhez már nincs rá közvetlenül szükség.
3. A blokk személyi igazolványa: src/block.json
Ez a modern blokkfejlesztés központi eleme. Itt definiálunk mindent, amit a WordPress-nek tudnia kell a blokkról: a nevét, ikonját, a beállításait (attribútumait), és hogy melyik JS/CSS fájlt kell betöltenie a szerkesztőben és a frontend oldalon.
src/block.json
{
"$schema": "https://schemas.wp.org/trunk/block.json",
"apiVersion": 3,
"name": "wphu/gorgetes-animacio-blokk",
"version": "1.3.0",
"title": "Görgetés Animáció (Egér)",
"category": "design",
"icon": "arrow-down-alt2",
"description": "Megjelenít egy animált egeret, ami a görgetésre elhalványul, színe és pozíciója állítható.",
"supports": {
"html": false,
"align": [ "left", "center", "right" ]
},
"attributes": {
"align": {
"type": "string",
"default": "center"
},
"color": {
"type": "string",
"default": "#333333"
}
},
"textdomain": "gorgetes-animacio-blokk",
"editorScript": "file:./index.js",
"script": "file:./scroll-fade.js",
"editorStyle": "file:./index.css",
"style": "file:./style-index.css",
"render": "file:./render.php"
}A lényeg: Tiszta, deklaratív módon írja le a blokk felépítését és függőségeit.
4. A szerkesztő agya: src/index.js
Ez a React-alapú kód felel a teljes admin oldali élményért. Létrehozza a blokk előnézetét, a jobb oldali sávban megjelenő színválasztót, és kezeli az adatok változását. Itt a legmodernebb, CSS változós módszert használjuk a dinamikus színezéshez.
src/index.js
import { registerBlockType } from '@wordpress/blocks';
import { useBlockProps, InspectorControls } from '@wordpress/block-editor';
import { PanelBody, ColorPalette } from '@wordpress/components';
import { __ } from '@wordpress/i18n';
// A stíluslapok importálása kulcsfontosságú a build folyamat miatt.
import './editor.scss';
import './style.scss';
import metadata from './block.json';
// Az SVG komponens, ami csak a "rajzot" tartalmazza, a stílust CSS-ből kapja.
const MouseIcon = () => (
<svg width="30px" height="50px" viewBox="0 0 30 50" aria-hidden="true" focusable="false">
<path className="scroll-mouse-body" d="M15,1.5 C22.45,1.5 28.5,7.54 28.5,15 L28.5,35 C28.5,42.45 22.45,48.5 15,48.5 C7.54,48.5 1.5,42.45 1.5,35 L1.5,15 C1.5,7.54 7.54,1.5 15,1.5 Z"/>
<circle className="scroll-mouse-wheel" cx="15" cy="12" r="4" />
</svg>
);
registerBlockType(metadata.name, {
edit: ({ attributes, setAttributes }) => {
const { color } = attributes;
// A useBlockProps-nak átadjuk a CSS változónkat.
const blockProps = useBlockProps({
style: { '--mouse-icon-color': color },
});
return (
<>
<InspectorControls>
<PanelBody title={__('Beállítások', 'gorgetes-animacio-blokk')}>
<p>{__('Egér színe', 'gorgetes-animacio-blokk')}</p>
<ColorPalette
value={color}
onChange={(newColor) => setAttributes({ color: newColor })}
disableCustomColors={false}
clearable={false}
/>
</PanelBody>
</InspectorControls>
<div {...blockProps}>
<MouseIcon />
</div>
</>
);
},
save: () => null,
});A lényeg: Tiszta szétválasztás a logika és a kinézet között. A JS csak az adatokat (a színt) kezeli, és átadja egy CSS változónak.
5. A kirakat motorja: src/render.php
Mivel a mi blokkunk dinamikus, ez a PHP fájl felel a végső HTML kód legenerálásáért a látogatók számára. Itt is a biztonságos esc_attr függvénnyel és a CSS változós módszerrel dolgozunk. A biztonságos programozásaról itt már írtam.
src/render.php
<?php
/**
* A blokk PHP renderelője, a 'best practice' CSS változós módszerrel.
*/
$color = $attributes['color'] ?? '#333333';
$wrapper_attributes = get_block_wrapper_attributes([
'style' => '--mouse-icon-color: ' . esc_attr($color),
]);
?>
<div <?php echo $wrapper_attributes; ?>>
<svg width="30px" height="50px" viewBox="0 0 30 50" aria-hidden="true" focusable="false">
<path class="scroll-mouse-body" d="M15,1.5 C22.45,1.5 28.5,7.54 28.5,15 L28.5,35 C28.5,42.45 22.45,48.5 15,48.5 C7.54,48.5 1.5,42.45 1.5,35 L1.5,15 C1.5,7.54 7.54,1.5 15,1.5 Z"/>
<circle className="scroll-mouse-wheel" cx="15" cy="12" r="4" />
</svg>
</div>A lényeg: A PHP felel az adatok biztonságos kiírásáért a HTML szerkezetbe.
6. A frontend effekt: src/scroll-fade.js
Ez a kicsi, de hatékony JavaScript kód figyeli a görgetést, és a beállított értékek szerint elhalványítja a blokkot. Teljesítmény-optimalizált, így nem lassítja az oldalt.
src/scroll-fade.js
document.addEventListener('DOMContentLoaded', () => {
const scrollMouseBlock = document.querySelector('.wp-block-wphu-gorgetes-animacio-blokk');
if (!scrollMouseBlock) { return; }
const fadeStart = 150;
const fadeEnd = 300;
const fadeDistance = fadeEnd - fadeStart;
let isTicking = false;
const handleScroll = () => {
const scrollY = window.scrollY;
let opacity = 1.0;
if (scrollY > fadeStart) {
const progress = (scrollY - fadeStart) / fadeDistance;
opacity = 1 - progress;
}
scrollMouseBlock.style.opacity = Math.max(0, Math.min(1, opacity));
isTicking = false;
};
window.addEventListener('scroll', () => {
if (!isTicking) {
window.requestAnimationFrame(handleScroll);
isTicking = true;
}
});
});A lényeg: Külön fájlban kezeli a frontend interaktivitást, tisztán tartva a többi logikától.
7. A stíluslapok: src/style.scss és src/editor.scss
Végül a „festék és tapéta”. Az egyik a frontend (style.scss), a másik a szerkesztő (editor.scss) kinézetéért felel. Mindkettő a CSS változónkat használja a színezéshez, de az igazításokat másképp kezelik, hogy mindenhol tökéletes legyen az eredmény.
src/style.scss (Frontend)
.wp-block-wphu-gorgetes-animacio-blokk {
position: relative;
min-height: 70px;
display: block;
transition: opacity 0.15s linear;
> svg { position: absolute; top: 50%; }
&.alignleft > svg { left: 0; transform: translateY(-50%); }
&.aligncenter > svg { left: 50%; transform: translate(-50%, -50%); }
&.alignright > svg { right: 0; left: auto; transform: translateY(-50%); }
}
.scroll-mouse-body { fill: none; stroke: var(--mouse-icon-color, #333); stroke-width: 2; }
.scroll-mouse-wheel { fill: var(--mouse-icon-color, #333); animation: scroll-wheel-animation-svg 2s infinite; }
@keyframes scroll-wheel-animation-svg {
0% { opacity: 1; transform: translateY(0); } 15% { opacity: 1; }
50% { opacity: 0; transform: translateY(20px); } 100% { opacity: 0; }
}src/editor.scss (Szerkesztő)
.wp-block[data-type="wphu/gorgetes-animacio-blokk"] {
width: 100%;
position: relative;
min-height: 70px;
display: flex;
&.alignleft { justify-content: flex-start; }
&.aligncenter { justify-content: center; }
&.alignright { justify-content: flex-end; }
> div { display: flex; align-items: center; }
}
// Az SVG stílusai itt is szükségesek az előnézethez, de az animációt a style.scss-ből örökli.
.scroll-mouse-body { fill: none; stroke: var(--mouse-icon-color, #333); stroke-width: 2; }
.scroll-mouse-wheel { fill: var(--mouse-icon-color, #333); animation: scroll-wheel-animation-svg 2s infinite; }A lényeg: A stílusok logikusan szét vannak választva, de a közös részek (az SVG kinézete) újrahasznosíthatók.
Ha a fenti fájlok a helyükön vannak, a blokk működésre kész – de előbb le kell fordítani a JavaScript kódot a böngészők által érthető formára. Ehhez szükség van egy fejlesztői környezetre, amely a React kódot kezelni tudja.
Hogyan keltsük életre?
Ha a fenti fájlok a helyükön vannak, a folyamat egyszerű:
- Telepítés: Nyisd meg a terminált a plugin főmappájában, és futtasd:
npm install - Fordítás: Futtasd a build parancsot:
npm run build - Aktiválás: Tömörítsd be a mappát (a
node_modulesnélkül), töltsd fel a WordPress oldaladra és aktiváld!
Így fog kinézni a plugin könyvtára a 2. lépés után:
Telepítés WordPress alá
Ha a node_modules mappát kizárod, és a többi fájlt (pl. build/, plugin főfájlok, package.json stb.) ZIP-be csomagolod, például:
egermutato-blokk.zip
akkor ez a csomag telepíthető bővítményként WordPress alá.
Innen egyébként letölthető: https://github.com/lorinczandrasX/egermutato-blokk/tree/main
Lépések:
- WordPress admin → Bővítmények → Új hozzáadása
- Kattints a Bővítmény feltöltése gombra
- Válaszd ki a
egermutato-blokk.zipfájlt - Telepítés és aktiválás
Ha minden helyesen lett buildelve (npm run build futott), akkor a blokk megjelenik a Gutenberg szerkesztő blokkjai között a megadott néven (pl. „Görgetés Animáció (Egér)” néven, amit a block.json-ban írtunk).
Node.js telepítése (egyszeri lépés)
Ez a lépés csak az első telepítéskor szükséges.
A React alapú Gutenberg blokkokhoz szükséges a Node.js környezet, amely tartalmazza az npm nevű csomagkezelőt is.
Tennivaló:
- Telepítsd a gépedre (Windows/Mac/Linux)
- Lépj a https://nodejs.org oldalra
- Töltsd le
Ha Windows rendszeren vagy és van telepítve choco (Chocolatey), akkor:
choco install nodejs-lts
A Chocolatey egy Windows-alapú csomagkezelő rendszer, amely lehetővé teszi, hogy szoftvereket és fejlesztői eszközöket (pl. Node.js, Git, Python, VS Code stb.) egyszerű parancssoros utasításokkal telepíts ahelyett, hogy manuálisan keresnéd és kattintgatnád végig az .exe telepítőket.
A lényeg nem az, hogy honnan és hogyan telepítetted a Node.js-t, hanem az, hogy rendelkezésre álljon a node és az npm parancs.
Ha ezek működnek a parancssorban (node -v, npm -v), akkor minden rendben van.
Block felépítés, hivatalos dokumentációk itt!
A dokumentáció említ két speciális fájlt, amikről eddig nem beszéltünk.
view.css (viewStyle a block.json-ban): Olyan stíluslap, ami a szerkesztőben és a frontenden is érvényesül. Akkor hasznos, ha a blokk kinézetének a két helyen pixelpontosan meg kell egyeznie.
view.js (viewScript a block.json-ban): Olyan JavaScript kód, aminek a szerkesztőben ÉS a frontend oldalon is le kell futnia. Például, ha egy interaktív slider blokkot készítenél, a slider logikájának mindkét helyen működnie kellene, hogy lásd az előnézetet.
A mi scroll-fade.js szkriptünk egy tipikus frontend-only szkript (a script kulcsszóval a block.json-ban), mert a szerkesztőben nincs értelme a görgetésre elhalványulásnak.
| Fájl | Szerepe | Mikor fut le / Hol érvényesül? |
| plugin.php | Plugin regisztrálása | Mindig |
| block.json | Blokk metaadatai, „személyi igazolvány” | Mindig |
| index.js | Fő JS belépési pont, regisztráció | Szerkesztő |
| edit.js | Szerkesztő nézet logikája | Szerkesztő |
| save.js | Statikus blokk HTML generálása | Szerkesztő (mentéskor) |
| render.php | Dinamikus blokk HTML generálása | Frontend |
| style.scss | Csak a frontend stílusai | Frontend |
| editor.scss | Csak a szerkesztő stílusai | Szerkesztő |
| view.js | Megosztott szkript | Szerkesztő ÉS Frontend |
| view.css | Megosztott stílusok | Szerkesztő ÉS Frontend |
| scroll-fade.js | Csak frontend szkript (a mi esetünkben) | Frontend |
További infó: https://developer.wordpress.org/block-editor/getting-started/fundamentals/file-structure-of-a-block/
Ez a cikk csak a jéghegy csúcsa volt. Ha igazán mélyre akarsz ásni, és olyan dolgokat is megismernél, amikről itt nem esett szó, a hivatalos WordPress Block Editor Kézikönyv a te bibliád. Elképesztő részletességgel, rengeteg példával mutat be mindent, amire valaha is szükséged lehet.
Végszó
Azért készült ez az írás, hogy megkapd azt a vázat, azt az alapvető megértést a fájlok és a logika mögött, amivel magabiztosan tudsz építkezni – akár egyedül, akár egy AI segítségével. Hogy ne csak egy „fekete doboz” legyen a kód, amit kaptál.
Most pedig menj, és építs valami fantasztikus sablont vagy plugint, vagy komplett weboldalt! Hibába futottál? Ctrl + Shift + R. Néha működik. Néha csak placebo. De néha: varázslat!
Vélemény, hozzászólás?