מדריך שימוש בתוסף CMB2 ליצירת Custom Meta Boxes

CMB2 (ראשי תיבות של Custom Meta Boxes 2) הוא ארגז כלים פופולרי למפתחים ליצירת metaboxes, שדות מותאמים וטפסים בוורדפרס. אם אתם משתמשים ב-ACF ליצירת שדות מותאמים, כדאי להכיר גם את CMB2 – הוא מציע גישה מבוססת קוד שמפתחים רבים מעדיפים.

במדריך זה נראה כיצד לרשום metaboxes באמצעות CMB2, להוסיף שדות, להציג אותם בצד הלקוח ולהשוות בינו לבין ACF.

מה זה CMB2 ולמה להשתמש בו?

CMB הם ראשי התיבות של Custom Meta Boxes. התוסף CMB2 מספק למפתחי וורדפרס ארגז כלים לבניית metaboxes, שדות מותאמים (Custom Fields) וטפסים.

באמצעות CMB2 תוכלו לנהל בקלות שדות meta עבור פוסטים, עבור מונחים של טקסונומיות, משתמשים, תגובות ואף תוכלו ליצור באמצעותו עמוד הגדרות עבור התבנית שלכם. אם תתנו מבט בעמוד התוסף תמצאו את ההגדרה הבאה:

"CMB2 is a meta box, custom fields, and forms library for WordPress that will blow your mind"

התוסף פותח על ידי WebDevStudios ויש לו מעל 200,000 התקנות אקטיביות. הגרסה האחרונה היא 2.11.0, אף שלא נבדקה מול מספר גרסאות וורדפרס אחרונות. למרות זאת, הוא ממשיך לעבוד היטב בפועל.

רישום Custom Meta Box באמצעות CMB2

כדי ליצור metabox, צרו פונקציה והצמידו אותה להוק cmb2_init שמספק התוסף:

add_action( 'cmb2_init', 'cmb2_add_metabox' );
function cmb2_add_metabox() {

	$prefix = '_yourprefix_';

}

הגדרנו משתנה $prefix כדי להבטיח שמזהי השדות שלנו יהיו ייחודיים ולא יתנגשו עם תוספים או תבניות אחרות.

כעת, צרו את ה-metabox באמצעות new_cmb2_box():

add_action( 'cmb2_init', 'cmb2_add_metabox' );
function cmb2_add_metabox() {

	$prefix = '_yourprefix_';

	$cmb = new_cmb2_box( array(
		'id'           => $prefix . 'metabox',
		'title'        => __( 'Metabox Title', 'cmb2' ),
		'object_types' => array( 'page', 'post' ),
		'context'      => 'normal',
		'priority'     => 'default',
	) );

}

שתי נקודות חשובות לגבי הפרמטרים:

• בשורה 7 השתמשנו ב prefix על מנת שהמזהה (ID) של metabox יהיה ייחודי.
• בשורה 9 הגדרנו כי metabox זה יופיע בסוגי התוכן עמודים ופוסטים באמצעות הפרמטר object_types.

CMB2 תומך בתכונות רבות נוספות ליצירת metaboxes. ראו את הרשימה המלאה של תכונות ה-metabox בדוקומנטציה הרשמית.

הוספת שדות ל-Meta Box

לאחר רישום ה-metabox, הוסיפו לו שדות. CMB2 תומך ביותר מ-30 סוגי שדות. הנה שדה טקסט פשוט:

$cmb->add_field( array(
    'name' => __( 'My First Text Field', 'cmb2' ),
    'id' => $prefix . 'text_field',
    'type' => 'text',
    'desc' => __( 'My First Text Field Description', 'cmb2' ),
) );

הנה דוגמה מלאה יותר עם מספר סוגי שדות (דוגמא א.):

add_action( 'cmb2_init', 'cmb2_sample_metaboxes' );
/**
 * Define the metabox and field configurations.
 */
function cmb2_sample_metaboxes() {

	// Start with an underscore to hide fields from custom fields list
	$prefix = '_yourprefix_';

	/**
	 * Initiate the metabox
	 */
	$cmb = new_cmb2_box( array(
		'id'            => 'test_metabox',
		'title'         => __( 'Test Metabox', 'cmb2' ),
		'object_types'  => array( 'page', ), // Post type
		'context'       => 'normal',
		'priority'      => 'high',
		'show_names'    => true, // Show field names on the left
		// 'cmb_styles' => false, // false to disable the CMB stylesheet
		// 'closed'     => true, // Keep the metabox closed by default
	) );

	// Regular text field
	$cmb->add_field( array(
		'name'       => __( 'Test Text', 'cmb2' ),
		'desc'       => __( 'field description (optional)', 'cmb2' ),
		'id'         => $prefix . 'text',
		'type'       => 'text',
		'show_on_cb' => 'cmb2_hide_if_no_cats', // function should return a bool value
		// 'sanitization_cb' => 'my_custom_sanitization', // custom sanitization callback parameter
		// 'escape_cb'       => 'my_custom_escaping',  // custom escaping callback parameter
		// 'on_front'        => false, // Optionally designate a field to wp-admin only
		// 'repeatable'      => true,
	) );

	// URL text field
	$cmb->add_field( array(
		'name' => __( 'Website URL', 'cmb2' ),
		'desc' => __( 'field description (optional)', 'cmb2' ),
		'id'   => $prefix . 'url',
		'type' => 'text_url',
		// 'protocols' => array('http', 'https', 'ftp', 'ftps', 'mailto', 'news', 'irc', 'gopher', 'nntp', 'feed', 'telnet'), // Array of allowed protocols
		// 'repeatable' => true,
	) );

	// Email text field
	$cmb->add_field( array(
		'name' => __( 'Test Text Email', 'cmb2' ),
		'desc' => __( 'field description (optional)', 'cmb2' ),
		'id'   => $prefix . 'email',
		'type' => 'text_email',
		// 'repeatable' => true,
	) );

	// Add other metaboxes as needed

}

את כל סוגי השדות הזמינים תמצאו בעמוד ה-GitHub של CMB2. התוסף כולל גם קובץ example-functions.php (צפו בו ב-GitHub) שמדגים כיצד ליצור כל סוג שדה.

ה-CMB2 Metabox Code Generator יכול לייצר עבורכם קוד של metaboxes ושדות ולחסוך זמן על קוד שגרתי. לרשימה מלאה של פרמטרים זמינים לשדות, ראו את תיעוד הפרמטרים של השדות.

הצגת שדות CMB2 בצד הלקוח

לאחר רישום metaboxes ושדות, תרצו להציג את הערכים השמורים בתבנית שלכם. השתמשו בפונקציה הסטנדרטית get_post_meta() כדי לשלוף את הנתונים.

העבירו כפרמטרים את מזהה הפוסט ואת מפתח השדה (כולל הקידומת):

<?php
// Grab the metadata from the database
$text = get_post_meta( get_the_ID(), '_yourprefix_text', true );

// Echo the metadata
echo esc_html( $text );
?>

עבור תבנית עמוד שמציגה את כל השדות מדוגמא א. לעיל:

<?php
/**
 * Example for Single Page Template that shows CMB2 Fields in your Theme.
**/
get_header(); ?>

		<div id="primary">
			<div id="content" role="main">

				<?php while ( have_posts() ) : the_post(); ?>

					<?php get_template_part( 'content', 'page' ); ?>

					<?php
					$text  = get_post_meta( get_the_ID(), '_yourprefix_text', true );
					$email = get_post_meta( get_the_ID(), '_yourprefix_email', true );
					$url   = get_post_meta( get_the_ID(), '_yourprefix_url', true );
					echo esc_html( $text );
					echo is_email( $email );
					echo esc_url( $url );
					?>

					<?php comments_template( '', true ); ?>

				<?php endwhile; // end of the loop. ?>

			</div><!-- #content -->
		</div><!-- #primary -->

<?php get_footer(); ?>

ACF מול CMB2: מה כדאי לבחור?

לשני התוספים יתרונות. ACF (בבעלות WP Engine מאז 2022) מספק ממשק ניהול מלוטש, פונקציות פנימיות כמו get_field() ותכונות כגון Flexible Content ו-Gutenberg Blocks. אולם, פונקציות אלו מוסיפות קריאות נוספות למסד הנתונים בהשוואה לפונקציות ליבה כגון get_post_meta().

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

ב-CMB2 בעיה זו לא קיימת. הוא שומר נתונים באמצעות פונקציות ה-meta הסטנדרטיות של וורדפרס, כך שהשדות נגישים גם אם התוסף מבוטל. הגדרות השדות חיות בקוד (לא במסד הנתונים), מה שמקל על ניהול גרסאות.

הפשרה ברורה: ACF קל יותר להגדרה ומתאים למתחילים, בעוד CMB2 מותאם למפתחים ומייצר קוד רזה וניוד יותר.

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

טיפים וטריקים ל-CMB2

הנה מספר טכניקות שימושיות בעבודה עם CMB2:

1. דריסת טקסט ברירת מחדל בשדות

חלק מהשדות ב-CMB2 כוללים טקסט ברירת מחדל שניתן לדרוס. לדוגמה, שדה מסוג file כולל כפתור עם הטקסט ״Add or Upload file״. דרסו אותו באמצעות הפרמטר options:

$cmb->add_field( array(
    'name'    => 'PDF',
    'id'      => $prefix . 'pdf',
    'type'    => 'file',
    'options' => array(
        'add_upload_file_text' => 'Upload PDF',
    ),
    'query_args' => array(
        'type' => 'application/pdf', // Make library only display PDFs.
    ),
) );

שימו לב לפרמטר options בשורה 5.

2. הזרקת תוכן סטטי לשדה

CMB2 מספק פרמטרים להזרקת תוכן HTML סביב שדות:

• before_field
• before_row
• before
• after
• after_row
• after_field

כך משתמשים בהם:

$cmb->add_field( array(
    'name'         => 'Testing Field Parameters',
    'id'           => $prefix . 'test_parameters',
    'type'         => 'text',
    'before_row'   => '<p>Testing <b>"before_row"</b> parameter</p>',
    'before'       => '<p>Testing <b>"before"</b> parameter</p>',
    'before_field' => '<p>Testing <b>"before_field"</b> parameter</p>',
    'after_field'  => '<p>Testing <b>"after_field"</b> parameter</p>',
    'after'        => '<p>Testing <b>"after"</b> parameter</p>',
    'after_row'    => '<p>Testing <b>"after_row"</b> parameter</p>',
) );

התוצאה נראית כך:

3. הגבלת שדה טקסט למספרים בלבד

השתמשו בפרמטר attributes כדי להגביל את הקלט למספרים:

$cmb_demo->add_field( array(
    'name' => __( 'My Number Field', 'theme-domain' ),
    'desc' => __( 'Numbers only', 'theme-domain' ),
    'id'   => $prefix . 'number',
    'type' => 'text',
    'attributes' => array(
        'type' => 'number',
        'pattern' => 'd*',
    ),
) );

שאלות נפוצות

שאלות נפוצות על יצירת metaboxes מותאמים עם CMB2:

סיכום

CMB2 הוא ארגז כלים רזה ומבוסס קוד ליצירת metaboxes ושדות מותאמים בוורדפרס. הוא שומר נתונים באמצעות פונקציות וורדפרס סטנדרטיות, מונע נעילה לתוסף ובטוח לכלול בתבניות או תוספים. למדריך ה-API המלא, סוגי השדות ושימוש מתקדם, ראו את התיעוד הרשמי של CMB2.