שימוש ב wp_localize_script להעברת מידע מ PHP ל JavaScript

אחד האתגרים שתיתקלו בהם כשאתם מפתחים תבניות וורדפרס הוא לגרום למידע בצד השרת (הנגיש באמצעות PHP) להיות זמין גם בקבצי ה-JavaScript שלכם. לדוגמה, ייתכן שיש לכם פופאפ שההודעה שלו צריכה להיות ניתנת לתרגום, או בקשת AJAX שצריכה את כתובת ה-admin.

וורדפרס מספקת דרך מובנית להעביר מידע מ-PHP ל-JavaScript. הגישה המסורתית היא wp_localize_script(), והגישה המודרנית המומלצת היא wp_add_inline_script(). בפוסט זה נסקור את שתיהן.

הפונקציה wp_localize_script()

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

חתימת הפונקציה נראית כך:

wp_localize_script( $handle, $object_name, $data );

בואו נסביר את הפרמטרים:

• $handle – ה-handle של הסקריפט אליו אתם מעבירים את המידע (אותו handle שהשתמשתם בו בעת ה-enqueue).
• $object_name – שם אובייקט ה-JavaScript שיכיל את המידע. חייב להיות מזהה JavaScript תקין – ללא מקפים או תווים מיוחדים. רצוי להשתמש ב-prefix כדי למנוע קונפליקטים עם סקריפטים אחרים.
• $data – מערך אסוציאטיבי של זוגות מפתח-ערך. יכול להיות מערך חד-ממדי או רב-ממדי.

דוגמה מעשית עם ACF

נניח שיש לכם שדה ACF בשם marketo_id בעמוד, ואתם צריכים להעביר את ערכו לקובץ JavaScript. ראשית, טענו את הסקריפט ולאחר מכן קראו ל-wp_localize_script():

function sv_enqueue_marketo_script() {
    wp_enqueue_script(
        'localize-marketo',
        get_stylesheet_directory_uri() . '/js/localize-marketo.js',
        array(),
        '1.0',
        true
    );

    wp_localize_script( 'localize-marketo', 'acfVars', array(
        'marketoId' => get_field( 'marketo_id' ),
    ));
}
add_action( 'wp_enqueue_scripts', 'sv_enqueue_marketo_script' );

שימו לב שהפרמטר הראשון של wp_localize_script() תואם ל-handle של הסקריפט. הפרמטר השני (acfVars) הופך לאובייקט JavaScript גלובלי, והפרמטר השלישי הוא מערך הנתונים.

העברת מידע מ ACF ל JavaScript באמצעות wp_localize_script

אם אתם רוצים ללמוד עוד על השימוש ב-ACF, עיינו במדריך הבסיסי ל-Advanced Custom Fields.

גישה למידע ב-JavaScript

בקובץ localize-marketo.js, גשו למידע דרך שם האובייקט והמפתח:

document.addEventListener( 'DOMContentLoaded', function() {
    var marketoId = acfVars.marketoId;
    console.log( marketoId );
});

המשתנה acfVars זמין באופן גלובלי מכיוון שוורדפרס מייצרת תגית <script> עם המידע ממש לפני הסקריפט שטענתם.

החלופה המודרנית: wp_add_inline_script()

למרות ש-wp_localize_script() עדיין עובדת, היא תוכננה עבור תרגומים ולא להעברת מידע כללי. ליבת וורדפרס ממליצה כיום להשתמש ב-wp_add_inline_script() בשילוב עם wp_json_encode() להעברת מידע מ-PHP ל-JavaScript.

תיעוד המפתחים של וורדפרס מציין במפורש שיש להשתמש ב-wp_localize_script() "רק כאשר אתם באמת רוצים לבצע לוקאליזציה של מחרוזות." להעברת מידע, wp_add_inline_script() היא הגישה המומלצת.

הנה אותה דוגמה בגישה המודרנית:

function sv_enqueue_marketo_script() {
    wp_enqueue_script(
        'localize-marketo',
        get_stylesheet_directory_uri() . '/js/localize-marketo.js',
        array(),
        '1.0',
        true
    );

    $data = array(
        'marketoId' => get_field( 'marketo_id' ),
    );

    wp_add_inline_script(
        'localize-marketo',
        'const acfVars = ' . wp_json_encode( $data ) . ';',
        'before'
    );
}
add_action( 'wp_enqueue_scripts', 'sv_enqueue_marketo_script' );

הפונקציה wp_add_inline_script() מקבלת שלושה פרמטרים:

• $handle – ה-handle של הסקריפט שאליו מצרפים את הקוד ה-inline.
• $data – קוד JavaScript בתור מחרוזת.
• $position – 'before' או 'after' (ברירת מחדל). השתמשו ב-'before' כדי שהמידע יהיה זמין כשהסקריפט שלכם נטען.

למה להעדיף את wp_add_inline_script()?

ישנם מספר יתרונות על פני wp_localize_script():

• אתם יכולים להעביר כל ערך JavaScript, לא רק אובייקטים – מחרוזות, מספרים, booleans ומערכים עובדים.
• קריאות מרובות לאותו handle מוסיפות מידע במקום לדרוס אותו.
• wp_json_encode() מבצעת escaping נכון למידע, ומונעת פרצות XSS.
• יש לכם שליטה מלאה על הצהרת המשתנה (const, let או var).

שאלות נפוצות

שאלות נפוצות בנושא העברת מידע מ-PHP ל-JavaScript בוורדפרס:

סיכום

להעברת מידע מ-PHP ל-JavaScript בוורדפרס, יש לכם שתי אפשרויות. הפונקציה המסורתית wp_localize_script() עדיין עובדת ומתאימה לשימושים פשוטים, במיוחד בלוקאליזציה של מחרוזות. להעברת מידע כללי, העדיפו את wp_add_inline_script() עם wp_json_encode() – היא נותנת לכם יותר גמישות, escaping נכון ומתאימה להמלצות הנוכחיות של ליבת וורדפרס.