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

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

מאז וורדפרס 5.8, מומלץ לרשום בלוקים באמצעות הקובץ block.json במקום להשתמש בפונקציות PHP. במדריך זה תלמדו כיצד ליצור בלוק ״קריאה לפעולה (CTA)״ באמצעות ACF ובשיטת block.json. בואו נתחיל!

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

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

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

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

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

• apiVersion: גרסת ה-API של הבלוק. מומלץ להשתמש בגרסה 3, שמאפשרת עבודה עם עורך הבלוקים בתוך iframe ומשפרת את בידוד הסגנונות.
• name: מזהה ייחודי לבלוק.
• title: שם הבלוק כפי שהוא מופיע בעורך.
• description: תיאור קצר של הבלוק.
• category: הקטגוריה שבה הבלוק יוצג בגוטנברג.
• icon: האייקון שמייצג את הבלוק בעורך.
• supports: מאפשר לקבוע תמיכה ביישור וכיבוי HTML.
• acf.renderTemplate: מציין את קובץ ה-PHP לרינדור הבלוק.
• style: מגדיר קובץ CSS שייטען עם הבלוק בעורך ובחזית.

שלב 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');

שלב 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

לאחר שסיימתם להוסיף את השדות, עברו להגדרות "כללי מיקום" (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. הגרסה החדשה משפרת משמעותית את חוויית העריכה – במקום מצב עריכה ישיר (inline), השדות נפתחים בפאנל צדדי ייעודי שמאפשר לראות את תצוגת הבלוק בזמן אמת תוך כדי עריכת השדות.

כדי לשדרג את הבלוק שלכם ל-V3, הוסיפו את המאפיין blockVersion לאובייקט acf בקובץ block.json:

"acf": {
    "mode": "preview",
    "renderTemplate": "custom-cta.php",
    "blockVersion": 3
}

בנוסף, מאז גרסה 6.7 של ACF (דצמבר 2025), ניתן להפעיל עריכה ישירה (Inline Editing) שמאפשרת ללחוץ ישירות על תוכן הבלוק בתצוגה המקדימה כדי לערוך אותו. כדי להפעיל את הפיצ'ר, הוסיפו "autoInlineEditing": true לאובייקט acf. שימו לב שפיצ'ר זה דורש blockVersion: 3.

שימוש בסוגי שדות מתקדמים

הדוגמה שלנו משתמשת בשדות בסיסיים כמו Text ו-Image, אך ACF מציע שדות מתקדמים נוספים שיכולים להעשיר את הבלוקים שלכם. לדוגמה, תוכלו להשתמש בשדה מסוג Repeater כדי ליצור רשימה דינמית של פריטים בתוך הבלוק, או בשדה מסוג Group כדי לארגן שדות קשורים תחת הורה אחד.

יש לציין כי בעת שימוש בשדות מורכבים יותר, חשוב לוודא שתבנית ה-PHP שלכם מטפלת בנתונים בצורה נכונה. למשל, בשדה Repeater יש להשתמש בלולאה עם have_rows() ו-the_row() כדי לעבור על כל שורה.

לסיכום

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

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

שאלות נפוצות

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