איך להשתמש בשדה Repeater של ACF בוורדפרס

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

תחשבו על שדה Repeater כעל טבלה שבה כל שורה יכולה להכיל כמה שדות-משנה (sub-fields) ומספר השורות אינו מוגבל אלא אם מגדירים מגבלה.

בפוסט הזה נראה כיצד להשתמש בשדה Repeater בצורה יעילה, נסביר איך להגדיר אותו וכיצד לבצע לולאה על הערכים שלו. בנוסף נציג דוגמאות, טיפים ואלטרנטיבות אפשריות.

מהו שדה ה-ACF Repeater?

שדה Repeater מאפשר להגדיר סט של שדות-משנה שניתן לשכפל שוב ושוב. זה למעשה קבוצה קטנה של שדות שניתן להעתיק ולשכפל בכל פעם שצריך.

• הצגת חברי צוות עם שם, תפקיד ותמונה
• שאלות נפוצות עם זוגות של שאלה/תשובה
• טבלאות מחיר
• הוראות שלב אחר שלב

איך יוצרים שדה Repeater

ניתן ליצור שדה Repeater בכל קבוצת שדות דרך הממשק של ACF:

1. הוסיפו שדה חדש ובחרו Repeater כסוג השדה
2. הגדירו שדות-משנה (כמו טקסט, תמונה, WYSIWYG וכו’)
3. אפשר להגדיר מגבלת שורות (פירוט בהמשך)
4. שמרו את קבוצת השדות ושייכו אותה לסוג פוסט או עמוד

הנה מידע נוסף שעשוי לעזור כשמגדירים Repeater:

הגדרת מספר מינימלי ומקסימלי של שורות

ACF מאפשר להגדיר כמה שורות נדרשות לפחות, וכמה שורות מותר להוסיף לכל היותר. דבר העוזר לשלוט על מבנה ותוכן העמוד.

• Minimum Rows: שימושי כשצריך שתהיה לפחות רשומה אחת (למשל FAQ אחד לפחות).
• Maximum Rows: מגביל את העומס של פלט, בעיקר כשעיצוב מצפה לכמות קבועה של פריטים (למשל שלוש עמודות).

תוכלו למצוא את ההגדרות של מינימום ומקסימום שורות בלשונית Validation.

סוגי תצוגה של Repeater: Table, Row, Block

כאשר מגדירים שדה Repeater, ניתן לבחור איך יוצגו שדות המשנה בממשק הניהול של וורדפרס. קיימות שלוש אופציות עיקריות:

• Table: מציג את השדות בטבלה, כל עמודה היא שדה אחר, בשורה אחת. מתאים לנתונים קצרים ופשוטים.
• Row: כל שדה מוצג אחד מתחת לשני. טוב לתוכן מפורט יותר או שדות ארוכים.
• Block: מציג את כל השדות בתוך קופסה מופרדת עם ריפוד. נהדר להפרדה ויזואלית של תוכן מורכב.

איך מציגים נתונים של שדה Repeater בתבנית

כדי להוציא נתונים משדה Repeater בצד האתר, משתמשים בלולאות של ACF כדי לעבור על כל שורה ולשלוף את שדות המשנה.

<?php
if ( have_rows('faq_items') ): ?>
    <div class="faq-wrapper">
        <?php while ( have_rows('faq_items') ): the_row();
            $question = get_sub_field('question');
            $answer = get_sub_field('answer');
        ?>
        <div class="faq-item">
            <h3><?php echo esc_html($question); ?></h3>
            <p><?php echo esc_html($answer); ?></p>
        </div>
        <?php endwhile; ?>
    </div>
<?php endif; ?>

זה עובד באופן הבא:

• have_rows('faq_items') – בודק אם יש שורות בשדה ה-faq_items
• the_row() – עובר לשורה הבאה כדי שנוכל לשלוף ממנה ערכים
• get_sub_field('question') ו-get_sub_field('answer') – שולפים ערכים מתוך השדה של כל שורה
• esc_html() – מוודא שהפלט בטוח ל-HTML, ומונע בעיות אבטחה

דוגמה זו תציג רשימה של שאלות ותשובות (FAQs) בתוך קונטיינר אחד. זו אחת מהשימושים הנפוצים, אבל אותו עיקרון עובד גם על חברי צוות, שלבים, פיצ’רים או כל תוכן שניתן לשכפל.

רוצים לבנות אזור שאלות ותשובות אינטראקטיבי? בדקו את המדריך המלא שלנו ליצירת עמוד FAQ בוורדפרס עם ACF Repeater ו-jQuery.

התוסף "Theme Code Pro"

התוסף Advanced Custom Fields: Theme Code Pro מקצר את העבודה ע"י יצירת קוד PHP מוכן לשימוש עבור כל שדות ה-ACF שלך.

לאחר יצירת קבוצת שדות, התוסף מציע קוד תבנית מוכן לפונקציות כמו get_field(), have_rows() ו-the_sub_field() – ובכך חוסך זמן ומפחית טעויות בקבצי התבנית שלך.

זה נראה כך:

שימוש בשדה Repeater עם תמונות

שדות-משנה ב-Repeater יכולים להיות מכל סוג, כולל העלאת תמונות. אם תרצו להציג תמונה שהועלתה ע"י המשתמש, למשל תמונת פרופיל של חבר צוות, תצטרכו לשלוף אותה נכון ולהציג אותה בצורה מאובטחת בתבנית שלכם.

$image = get_sub_field('team_member_photo');
if( $image ):
    echo '<img src="' . esc_url($image['sizes']['medium']) . '" alt="' . esc_attr($image['alt']) . '">';
endif;

בואו נפרק את הקוד:

• get_sub_field('team_member_photo') – שולף את נתוני התמונה מהשדה team_member_photo.
• $image['sizes']['medium'] – מציג את גודל התמונה "medium" שוורדפרס יוצרת אוטומטית.
• $image['alt'] – מוציא את טקסט ה-alt של התמונה כפי שהוזן בספריית המדיה.
• esc_url() ו-esc_attr() – דואגים שהפלט יהיה בטוח ל-HTML וימנע בעיות אבטחה.

חשוב: הגדרה נכונה של פורמט החזרה

כדי שקוד זה יעבוד, יש להגדיר את פורמט ההחזרה של שדה התמונה ל-"Image Array" בהגדרות שדה ה-ACF.

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

אם תבחרו "Image URL" או "Image ID", הקוד הנ"ל לא יעבוד ללא שינויים.

בחירת פורמט Image Array נותנת הכי הרבה גמישות ומומלצת כאשר רוצים שליטה מלאה על הצגת התמונות בתבנית.

אפשר גם להשתמש בגדלים נוספים כגון thumbnail, large או בגדלים מותאמים שהוגדרו עם add_image_size() בתבנית שלכם.

טיפים לביצועים ושימוש נכון

כדי להפיק את המירב משדה Repeater, כדאי לזכור את ההמלצות הבאות:

• תמיד להגן על הפלט: השתמשו ב-esc_html(), esc_url() ו-esc_attr() לפי הצורך
• הימנעו מקינון עמוק של Repeaters כדי לשמור על ביצועים טובים בממשק הניהול
• העדיפו רישום שדות ב-PHP לשליטה מלאה וגרסאות קוד
• לחלופין, הפעילו את אפשרות Local JSON של ACF לסנכרון קבוצות שדות עם קבצים וניהול ב-Git
• בלייאאוטים מורכבים במיוחד, עדיף לפעמים להשתמש בשדה Flexible Content במקום Repeaters מקוננים

דוגמה מתקדמת: גריד דינמי של חברי צוות עם Tailwind

בואו נרחיב את השימוש עם דוגמה אמיתית: גריד רספונסיבי ומעוצב של חברי צוות עם Tailwind CSS. נוסיף תמונת ברירת מחדל, alt דינמי, וקלאסים של Tailwind לעיצוב ונגישות.

<?php
if ( have_rows('team_members') ): ?>
    <div class="grid grid-cols-1 sm:grid-cols-2 lg:grid-cols-3 gap-6">
        <?php while ( have_rows('team_members') ): the_row();
            $name   = get_sub_field('name');
            $role   = get_sub_field('role');
            $photo  = get_sub_field('photo');
            $photo_url = $photo['sizes']['medium'] ?? get_template_directory_uri() . '/img/placeholder.jpg';
            $alt_text  = $photo['alt'] ?? $name;
        ?>
        <div class="bg-white shadow-md rounded-xl p-6 text-center flex flex-col items-center transition hover:scale-105 duration-200">
            <img src="<?php echo esc_url($photo_url); ?>" alt="<?php echo esc_attr($alt_text); ?>" class="w-24 h-24 object-cover rounded-full mb-4">
            <h3 class="text-xl font-bold"><?php echo esc_html($name); ?></h3>
            <p class="text-gray-500"><?php echo esc_html($role); ?></p>
        </div>
        <?php endwhile; ?>
    </div>
<?php endif; ?>

מה אנו רואים בדוגמה זו:

• תמונת ברירת מחדל: אם לא הועלתה תמונה, יוצג placeholder אוטומטי.
• alt דינמי: אם לתמונה אין alt, יוצג שם המשתמש.
• עיצוב Tailwind: כולל shadow, פינות מעוגלות ואפקט hover.
• גריד רספונסיבי: עמודה אחת במובייל עד שלוש עמודות בדסקטופ.

דפוס זה מושלם לאזורי צוות, רשימות עובדים או כרטיסי שירות. דינמי לחלוטין ונשלט ע"י העורך דרך ACF.

מתי לא להשתמש ב-Repeaters?

למרות הגמישות, Repeaters הם לא תמיד הבחירה הנכונה, במיוחד כשמדובר במידע רב או מידע שדורש קשרים מסוימים (relational fields).

• השתמשו ב-Custom Post Types לנתונים שדורשים ארכיון
• הימנעו מ-Repeaters עם מאות שורות, זה עלול להאט את ממשק הניהול
• הימנעו מ-Repeaters כאשר התוכן דורש קטגוריות, תגיות, או אפשרויות פרסום כמו טיוטות או תזמון. במקרים כאלה, עדיף ליצור סוג פוסט מותאם.

סיכום

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

אם אתם בתחילת הדרך עם ACF, מומלץ לעיין במדריך המתחילים שלנו ל-Advanced Custom Fields. רוצים לבנות אזור דינמי ומתקדם יותר? למדו איך להציג Repeater בסליידר בעזרת המדריך שלנו על בניית קרוסלה בוורדפרס עם Slick ו-ACF.