הוספת בלוקים חדשים לגוטנברג באמצעות ACF והקובץ block.json

גוטנברג, עורך הבלוקים של וורדפרס, מפשט את יצירת התוכן והניהול שלו בצורה ויזואלית ונוחה. בעזרת התוסף Advanced Custom Fields (ACF), תוכלו ליצור בקלות בלוקים מותאמים אישית לגוטנברג, בלי להכיר JavaScript לעומק.

מאז וורדפרס 5.8, מומלץ לרשום בלוקים באמצעות הקובץ block.json במקום להשתמש בפונקציות PHP. הפונקציה הישנה acf_register_block_type() נחשבת כיום ל-legacy, ומגרסה 6.0 ואילך ACF ממליץ להשתמש ב-block.json לכל בלוק חדש.

נבנה יחד בלוק ״קריאה לפעולה״ (CTA) מאפס: קובץ ההגדרות, קבוצת השדות, תבנית הרינדור והעיצוב. כל מה שמופיע כאן נכתב מול ACF PRO 6.8.9 ווורדפרס 7.0, ולצד כל פיצ׳ר חדש ציינו איזו גרסה הוא דורש, כך שהמדריך יישאר רלוונטי גם אם האתר שלכם נמצא גרסה או שתיים מאחור.

שלב 1: יצירת קובץ ההגדרות של הבלוק (block.json)

בתוך תיקיית התבנית שלכם, נווטו אל /template-parts/blocks/custom-cta/ וצרו קובץ בשם block.json. הקובץ הזה מגדיר את מאפייני הבלוק:

{
  "apiVersion": 3,
  "name": "acf/custom-cta",
  "title": "Custom CTA Block",
  "description": "בלוק קריאה לפעולה מותאם אישית עם תמונה, כותרת, תיאור וכפתור.",
  "category": "design",
  "icon": "megaphone",
  "keywords": ["cta", "call to action", "button"],
  "supports": {
    "align": ["wide", "full"],
    "html": false
  },
  "acf": {
    "blockVersion": 3,
    "renderTemplate": "custom-cta.php"
  },
  "style": ["file:./custom-cta.css"]
}

שימו לב: המאפיין style מגדיר קובץ CSS שייטען אוטומטית כשהבלוק מופיע בעורך וגם בחזית האתר. מאז וורדפרס 6.5, קיים גם המאפיין viewStyle שטוען סגנונות בחזית בלבד, וכן editorStyle לסגנונות בעורך בלבד. כך תוכלו לוודא שהעיצובים שלכם נטענים בדיוק בסביבה הנכונה.

הסבר על המאפיינים המרכזיים:

• apiVersion: גרסת ה-API של הבלוק. יש להשתמש בגרסה 3, שמאפשרת לעבוד עם עורך הבלוקים בתוך iframe ומשפרת את בידוד הסגנונות. מוורדפרס 6.9 ואילך זו הגרסה היחידה שסכמת block.json מקבלת, ובלוקים שרשומים בגרסה ישנה יותר מייצרים אזהרה בקונסולה.
• name: מזהה ייחודי לבלוק, חייב להתחיל בקידומת acf/.
• category: הקטגוריה שבה הבלוק יוצג בגוטנברג.
• icon: האייקון שמייצג את הבלוק בעורך.
• supports: מאפשר לקבוע תמיכה ביישור ובהשבתת HTML.
• acf.renderTemplate: מציין את קובץ ה-PHP שמרנדר את הבלוק.
• acf.blockVersion: הגדרה של 3 מפעילה את ACF Blocks V3, שדורש ACF PRO 6.6 ומעלה. אם לא תגדירו אותו, ACF יבחר עבורכם: גרסה 2 עד וורדפרס 7.0, וגרסה 3 מוורדפרס 7.1 ואילך בגרסאות ACF PRO 6.8.9 ומעלה. נרחיב על כך בהמשך.
• style: מערך של קבצי CSS שנטענים גם בעורך וגם בחזית. השתמשו בקידומת file:./ לנתיבים יחסיים.

שלב 2: רישום הבלוק בקובץ functions.php

למרות שקובץ block.json חוסך את הצורך ברישום ידני, עדיין צריך לוודא שוורדפרס מזהה את הבלוק. הוסיפו את הקוד הבא לקובץ functions.php:

function register_acf_blocks() {
    register_block_type(get_template_directory() . '/template-parts/blocks/custom-cta/block.json');
}
add_action('init', 'register_acf_blocks');

אם יש לכם כמה בלוקים מותאמים, תוכלו לרשום את כולם בלולאה אחת במקום לחזור על אותו קוד עבור כל בלוק:

function register_acf_blocks() {
    $blocks = glob(get_template_directory() . '/template-parts/blocks/*/block.json');
    foreach ($blocks as $block) {
        register_block_type($block);
    }
}
add_action('init', 'register_acf_blocks');

בשיטה הזו כל בלוק חדש שתוסיפו לתיקייה ייקלט אוטומטית, בלי לגעת שוב בקובץ functions.php.

שלב 3: יצירת קבוצת השדות ב-ACF

1. גשו אל ACF > Field Groups ולחצו על Add New.

2. תנו לקבוצה את השם Custom CTA Block Fields והוסיפו את השדות הבאים:

• Title: שדה מסוג Text עבור כותרת ה-CTA.
• Description: שדה מסוג Text Area עבור תיאור ה-CTA.
• Image: שדה מסוג Image עבור תמונה.
• Button Text: שדה מסוג Text עבור טקסט הכפתור.
• Button URL: שדה מסוג URL עבור קישור הכפתור.
• Background Color: שדה מסוג Color Picker עבור צבע הרקע.

כל סוגי השדות של ACF עובדים בתוך בלוק, כך שברגע שה-CTA עובד תוכלו להחליף שדה בשדה Repeater ליצירת רשימה דינמית, או בשדה Group כדי לארגן יחד שדות קשורים. שדות כאלה דורשים את לולאת have_rows() הרגילה בתבנית, ומכיוון שאותה תבנית מרנדרת גם את התצוגה המקדימה בעורך, בדיקה חסרה תיראה כמו בלוק שבור בזמן שמישהו עורך את העמוד.

זה נראה כך:

יצירת קבוצת השדות של הבלוק ב-ACF

לאחר שסיימתם להוסיף את השדות, עברו להגדרות "כללי מיקום" (Location Rules) בעורך קבוצת השדות של ACF. הגדירו את הכלל כך ש-בלוק יהיה שווה ל-Custom CTA Block.

שלב 4: יצירת תבנית הבלוק

בתיקיית התבנית שלכם, צרו את הקובץ custom-cta.php עם הקוד הבא:

<?php
$title = get_field('title');
$description = get_field('description');
$image = get_field('image');
$button_text = get_field('button_text');
$button_url = get_field('button_url');
$background_color = get_field('background_color');
?>

<div class="custom-cta-block" style="background-color: <?php echo esc_attr($background_color); ?>">
    <?php if ($image): ?>
        <img src="<?php echo esc_url($image['url']); ?>" alt="<?php echo esc_attr($image['alt']); ?>" class="cta-image" />
    <?php endif; ?>

    <div class="cta-content">
        <?php if ($title): ?>
            <h3 class="cta-title"><?php echo esc_html($title); ?></h3>
        <?php endif; ?>

        <?php if ($description): ?>
            <p class="cta-description"><?php echo esc_html($description); ?></p>
        <?php endif; ?>

        <?php if ($button_text && $button_url): ?>
            <a href="<?php echo esc_url($button_url); ?>" class="cta-button">
                <?php echo esc_html($button_text); ?>
            </a>
        <?php endif; ?>
    </div>
</div>

שלב 5: יצירת קובץ ה-CSS

צרו קובץ בשם custom-cta.css והוסיפו את הקוד הבא:

.custom-cta-block {
    padding: 40px;
    border-radius: 15px;
    text-align: center;
    color: #fff;
    max-width: 700px;
    margin: 30px auto;
    box-shadow: 0 4px 20px rgba(0, 0, 0, 0.1);
}

.custom-cta-block:hover {
    transform: translateY(-5px);
}

.cta-image {
    max-width: 120px;
    margin-bottom: 20px;
    border-radius: 50%;
    border: 4px solid #fff;
}

.cta-title {
    font-size: 28px;
    margin: 15px 0;
    font-weight: 700;
}

.cta-description {
    font-size: 18px;
    margin-bottom: 20px;
    line-height: 1.5;
}

.cta-button {
    display: inline-block;
    padding: 12px 25px;
    background-color: #ff6b6b;
    color: #fff;
    text-decoration: none;
    border-radius: 25px;
    font-weight: bold;
}

.cta-button:hover {
    background-color: #e05656;
}

שדרוג ל-ACF Blocks V3

מאז גרסה 6.6 של ACF (אוקטובר 2025) קיימת גרסה חדשה של בלוקי ACF בשם ACF Blocks V3, והיא משנה את חוויית העריכה מהיסוד. בלוק V3 לעולם לא יוצא מהתצוגה המקדימה: השדות יושבים בפאנל צדדי ייעודי, ואייקון עיפרון פותח את אותו טופס בחלון רחב יותר כשצריך מקום לתוכן ארוך.

בלוקים בגרסה 2 עובדים אחרת. הם משתמשים במאפיין mode כדי לעבור בין טופס עריכה פנימי לבין התצוגה המקדימה, כשברירת המחדל ברישום דרך block.json היא auto. בבלוק V3 המאפיין הזה חסר משמעות, מכיוון ש-ACF מעביר בלוקים כאלה למנגנון רינדור שלא בונה כלל את הטופס הפנימי.

במשך תקופה ארוכה כל בלוק שנרשם דרך block.json התחיל בגרסה 2, והשדרוג נעשה בלוק אחרי בלוק. גרסה 6.8.9 של ACF (אוגוסט 2026) שינתה את זה: בלוק שלא מצהיר על גרסה מקבל כעת גרסה 3 כברירת מחדל בוורדפרס 7.1 ואילך. בגרסאות מוקדמות יותר של וורדפרס ברירת המחדל הישנה נשארת, כך שאותה תבנית בדיוק יכולה להתנהג אחרת מאתר לאתר. הצהרה מפורשת פותרת את הבעיה, כי ערך שנכתב ב-blockVersion גובר בכל מקרה:

"acf": {
    "renderTemplate": "custom-cta.php",
    "blockVersion": 3,
    "autoInlineEditing": true
}

דווקא המאפיין השני הוא זה שכדאי לנסות קודם. autoInlineEditing, שנוסף בגרסה 6.7 של ACF (דצמבר 2025), מאפשר לעורכים ללחוץ על כל אלמנט בתצוגה המקדימה שמכיל אך ורק ערך של שדה בודד, ולהקליד ישירות בתוך הבלוק. עד גרסה 6.8.8 השדות האלה דרשו לחיצה מיותרת אחת לפני שהיה אפשר להקליד בהם, וגרסה 6.8.9 תיקנה את זה.

לעבור על כל קובץ block.json בתבנית ותיקה זו עבודה מייגעת, ולכן יש ב-ACF גם פילטר שמשפיע על בלוקים שלא הגדירו גרסה בעצמם:

add_filter( 'acf/blocks/default_block_version', function ( $version, $block ) {
    return 3;
}, 10, 2 );

הארגומנט $block מכיל את הגדרות הבלוק, כך שאפשר להעביר את רוב התבנית לגרסה 3 ולהשאיר בלוקים מסוימים בגרסה 2 לפי שם, עד שתספיקו לטפל בהם.

בלוקים שעדיף שלא ירנדרו תצוגה מקדימה

יש בלוקים שתצוגה מקדימה רק מפריעה להם: בלוק שמטפל בטופס, בלוק שהפלט שלו תלוי בפרמטרים ב-URL, או כל בלוק שצריך נתונים אמיתיים מהבקשה עצמה. במקרים כאלה תבנית הרינדור נופלת בעורך או מציגה משהו מטעה. גרסה 6.8.9 של ACF הוסיפה אפשרות לוותר על התצוגה בבלוקי V3:

"acf": {
    "renderTemplate": "custom-cta.php",
    "blockVersion": 3,
    "renderPreview": false
}

במקרה כזה העורך מציג placeholder עם האייקון של הבלוק, הכותרת שלו וכפתור Edit Block, ולא מריץ את תבנית הרינדור כלל. ACF מחיל את אותו placeholder גם מיוזמתו, כשבלוק V2 ישן ששילב "mode": "edit" עם "supports": { "mode": false } עובר לגרסה 3, מכיוון שזה בדיוק מה שהשילוב הזה נועד לבטא.

תמיכה ב-InnerBlocks

בלוקי ACF תומכים באופן מלא ב-InnerBlocks, כלומר באפשרות לקנן בלוקים אחרים של גוטנברג בתוך הבלוק המותאם שלכם. זה שימושי לבלוקים שזקוקים לאזור תוכן גמיש, למשל בלוק layout עם עמודת טקסט ועמודת מדיה.

כדי להוסיף את היכולת, שלבו את הרכיב <InnerBlocks /> בתבנית הרינדור:

<div class="my-block-wrapper">
    <!-- פלט של שדות ACF -->
    <h3><?php echo esc_html(get_field('heading')); ?></h3>

    <!-- אזור ה-InnerBlocks -->
    <div class="inner-content">
        <InnerBlocks />
    </div>
</div>

כל בלוק יכול להכיל רכיב <InnerBlocks /> אחד בלבד. בנוסף, אפשר להגדיר יחסי הורה וילד בקובץ block.json, וכך להגביל אילו בלוקים מותר לקנן בתוך הבלוק שלכם.

apiVersion 3 בוורדפרס 7.x

גרסת ה-API של הבלוקים השתנתה כבר כמה פעמים, והרבה מדריכים עדיין מתארים את התוכנית הישנה:

• וורדפרס 6.9 (דצמבר 2025) צמצמה את סכמת block.json כך שרק apiVersion: 3 עובר ולידציה, והוסיפה אזהרה בקונסולה לבלוקים שרשומים בגרסה ישנה יותר.
• וורדפרס 7.0 (מאי 2026) מריצה את עורך הפוסטים בתוך iframe, אבל רק כאשר כל הבלוקים בעמוד נמצאים בגרסה 3. בלוק ישן אחד בתוכן מבטל את ה-iframe עבור העורך כולו.
• וורדפרס 7.1 (אוגוסט 2026) ביטלה את מנגנון הנסיגה הזה. מעכשיו העורך רץ תמיד בתוך iframe, ללא קשר לגרסת ה-API שהבלוקים שלכם מצהירים עליה.

גרסה 3 מעולם לא הפכה לחובה של ממש, ובלוק בגרסה 2 ימשיך להיות מרונדר. הוא פשוט כבר לא יכול להישאר מחוץ ל-iframe. בבלוק ACF שמרונדר ב-PHP זה לרוב לא סיפור, מכיוון שתבנית הרינדור רצה בצד השרת. היוצא מן הכלל הוא בלוק שמגיע עם סקריפט עורך משלו: כל קוד שפונה ל-document או ל-window הגלובליים צריך לגשת אליהם דרך ownerDocument ו-defaultView.

גרסת הבלוק של ACF היא הגדרה נפרדת, ובוורדפרס 7.1 שתי המערכות נפגשות. עריכה בגרסה 2 בונה את הממשק שלה מקבצי JavaScript ו-CSS שנטענים ב-wp-admin, ובעורך שרץ כולו בתוך iframe הקבצים האלה כבר לא זמינים. זו הסיבה שגרסה 6.8.9 שינתה את ברירת המחדל. אתר שצריך עוד זמן יכול להיעזר בתוסף הזמני acf-blocks-v2-iframe-compatibility של ACF, שמזהה בלוקים בגרסה 2 ומכריח את העורך לצאת שוב מה-iframe. הוא נכנס לפעולה רק כשבאמת רשום בלוק כזה, וכדאי להתייחס אליו כאל גשר ולא כפתרון קבע.

שאלות נפוצות

שאלות נפוצות בנושא יצירת בלוקים מותאמים אישית לגוטנברג באמצעות ACF:

לסיכום

לאורך השלבים כאן בניתם בלוק גוטנברג מותאם אישית ועובד: קובץ ההגדרות, הרישום ב-PHP, קבוצת השדות, תבנית הרינדור וקובץ ה-CSS. אם אתם פותחים היום בלוק חדש על ACF PRO 6.6 ומעלה, כדאי להגדיר "blockVersion": 3 כבר מההתחלה. חוויית העריכה טובה יותר, ובוורדפרס 7.1 זו ממילא ברירת המחדל, כך שהגדרה מפורשת רק מוודאת שהבלוק יתנהג אותו דבר בכל אתר.

להמשך, אפשר לקרוא על ACF Synchronized JSON כדי לשמור את קבוצת השדות בניהול גרסאות לצד הבלוק עצמו.

אם נתקלתם בבעיות או יש לכם שאלות, מוזמנים לכתוב לנו בתגובות!