הדרך הנכונה לטעון סקריפטים בממשק הניהול של וורדפרס

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

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

טעינת סקריפטים בממשק הניהול – נכון ולא נכון

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

function sv_loading_scripts_wrong() {
    echo '<script type="text/javascript" src="https://ajax.googleapis.com/ajax/libs/jquery/1.7.2/jquery.min.js"></script>';
}
add_action('admin_head', 'sv_loading_scripts_wrong');

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

מה אם היינו רוצים לטעון סקריפט כלשהו משלנו המשתמש ב jQuery אך לא את jQuery עצמה? היינו יכולים לעשות משהו כזה:

function sv_loading_scripts_wrong() {
    echo '<script type="text/javascript" src="https://yoursite.com/path/to/custom.js"></script>';
}
add_action('admin_head', 'sv_loading_scripts_wrong');

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

שתי דוגמאות אלו אינן היחידות שיכולות להיות שגויות כאשר טוענים את jQuery או סקריפט אחר כלשהו. הנה דוגמה נוספת שאינה תקינה:

function sv_loading_scripts_wrong_again() {
    wp_enqueue_script('custom-js', 'wp-content/my-plugin-dir/js/custom.js');
}
add_action('admin_init', 'sv_loading_scripts_wrong_again');

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

הסיבות מדוע דרך זו אינה נכונה

הסיבה הראשונה מדוע דוגמה זו אינה נכונה היא השימוש בהוק admin_init לטעינת הסקריפט וזהו אינו ההוק הנכון. לחילופין – יש להשתמש בהוק admin_enqueue_scripts על מנת לוודא כי הסקריפטים נטענים בזמן הנכון.

הסיבה השנייה שהדוגמה אינה תקינה היא שבמקרה זה,  כמו בשתי הדוגמאות הראשונות, הקובץ custom.js נטען בכל עמוד ועמוד בממשק הניהול של וורדפרס וזה כמובן אינו תקין. תמיד יש לשמור על יעילות הקוד ולוודא כי משאבים לא מבוזבזים לשווא, כלומר שהסקריפט ייטען אך ורק היכן שהוא נחוץ.

והסיבה השלישית שהקוד אינו תקין היא כי אנו משתמשים בנתיב רלטיבי (relative path) לקובץ custom.js. יכול להיות שהוא ייטען כראוי בהתקנות מסויימות של וורדפרס ובהתקנות אחרות ייכשל במידה וטענתם אותו כך בתוסף שכתבתם לצורך העניין. תמיד יש לטעון סקריפטים עם הנתיב המלא (complete path).

איך נתקן את שלושת השגיאות הללו? כדאי שנתחיל בבחירת ההוק הנכון:

function sv_load_scripts() {
	wp_enqueue_script('custom-js', 'wp-content/my-plugin-dir/js/custom.js');
}
add_action('admin_enqueue_scripts', 'sv_load_scripts');

כבר נראה יותר טוב, אך לא מספק.

רצוי שנסדר את העניין בו הסקריפט נטען עם נתיב רלטיבי. בכדי לעשות זאת, נדפיס את הנתיב המדוייק בו הקובץ יושב. במידה ואנו כותבים תוסף כלשהו, יש להדפיס את הנתיב לתיקייה באמצעות הפונקציה  plugin_url(). בהנחה והקובץ custom.js קיים בתוך תיקיית js אשר בתיקייה הראשית של התוסף – הפונקציה תראה בצורה הבאה:

plugins_url( 'js/custom.js' , dirname(__FILE__) )

הוסיפו קוד זה לפונקציה שלנו ותקבלו את הקוד הבא:

function sv_load_scripts() {
    wp_enqueue_script( 'custom-js', plugins_url( 'js/custom.js' , dirname(__FILE__) ) );
}
add_action('admin_enqueue_scripts', 'sv_load_scripts');

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

טעינת סקריפטים בעמודים ספציפיים בוורדפרס

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

בדוגמה הראשונה, נניח ואנו מעוניינים לטעון קובץ Javascript מסויים בעמוד edit.php, זהו העמוד/הקובץ הראשי שנטען כאשר אנו מביטים ברשימת הפוסטים, העמודים או סוגי התוכן המותאמים.

function sv_load_scripts($hook) {

    if( $hook != 'edit.php' )
        return;

    wp_enqueue_script( 'custom-js', plugins_url( 'js/custom.js' , dirname(__FILE__) ) );
}
add_action('admin_enqueue_scripts', 'sv_load_scripts');

קוד זה מתאר את המצב הבא: אם איננו בעמוד edit.php צא ואל תמשיך עם הפונקציה, מכאן שהקובץ custom.js ייטען אך ורק כאשר אנחנו בעמוד edit.php.

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

function sv_load_scripts($hook) {

    if( $hook != 'edit.php' && $hook != 'post.php' && $hook != 'post-new.php' )
        return;
    
    wp_enqueue_script( 'custom-js', plugins_url( 'js/custom.js' , dirname(__FILE__) ) );
}
add_action('admin_enqueue_scripts', 'sv_load_scripts');

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

• index.php – לוח הבקרה
• upload.php – ספריית המדיה
• edit-comments.php – רשימת התגובות
• comment.php – עמוד עריכת תגובה ספציפית
• themes.php – עיצוב > תבניות
• widgets.php – עיצוב > ווידג׳טים
• nav-menus.php – עיצוב > תפריטים
• plugins.php – תוספים
• users.php – משתמשים
• options-general.php – הגדרות > כללי
• options-writing.php – הגדרות > כתיבה

רוב שמות העמודים מובנים מאליהם, אך אם אינכם סגורים על שם הדף, פשוט גשו לאותו עמוד בממשק הניהול של וורדפרס ותנו מבט בכתובת (url) ותמצאו את שם הקובץ המבוקש. אך מה לגבי עמודים מותאמים בממשק הניהול? אני מתכוון לעמודי הגדרות אותם אתם יוצרים בעצמכם..

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

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

עמוד הגדרות נוצר בדרך כלל בצורה הבאה:

function sv_create_settings_page() {
    global $sv_settings_page;
    $sv_settings_page = add_options_page(__('My Plugin Settings', 'my-domain'), __('Plugin Settings', 'my-domain'), 'manage_options', 'my-page-slug', 'sv_callback_function');
}
add_action('admin_menu', 'sv_create_settings_page');

עמוד ההגדרות נשמר (במקרה זה) במשתנה גלובלי בשם $sv_settings_pages. משתנה זה יהיה זהה למשתנה $hook בפונקציה admin_enqueue_scripts, ומכיוון והוא משתנה גלובלי ניתן לגשת אליו בצורה הבאה:

function sv_load_scripts($hook) {
 
	global $sv_settings_page;
 
	if( $hook != $sv_settings_page ) 
		return;
 
	wp_enqueue_script( 'custom-js', plugins_url( 'js/custom.js' , dirname(__FILE__) ) );
}
add_action('admin_enqueue_scripts', 'sv_load_scripts');

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

תגובות ומחשבות יתקבלו בברכה… 🙂