הבנת הוקים בוורדפרס: מדריך לשימוש ב-Actions ו-Filters

אם אתם בענייני פיתוח וורדפרס, לא תוכלו להתעלם מהוקים (Actions & Filters) להרבה זמן לפני שתהיו מוכרחים לרדת לעומק ולהבין את המשמעות של אותם הוקים בוורדפרס וכיצד להשתמש בהם.

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

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

הסבר על המונחים

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

פעולה (Action) 

פעולה בוורדפרס היא הוק המתבצע בזמן ספציפי כאשר וורדפרס רצה ומאפשר לכם לבצע פעולה מסויימת באותו זמן. פעולה למשל יכולה להיות יצירת פוסט מותאם אישית (Custom Post Type) כאשר וורדפרס מאותחלת או אף שיתוף הפוסט שלכם בפייסבוק כאשר אתם מפרסמים פוסט.

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

פילטר (Filter)

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

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

סוגים של פעולות ופילטרים

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

• Actions Run During a Typical Request
• Actions Run During an Admin Page Request
• Post, Page, Attachment, and Category Actions (Admin)
• Comment, Ping, and Trackback Actions
• Blogroll Actions
• Feed Actions
• Template Actions
• Administrative Actions
• Dashboard “Right Now” Widget Actions

תמצאו ב WordPress Codex עמוד דומה המציג את הפילטרים הקיימים לרשותכם ואותם פילטרים מחולקים גם כן לפי קטגוריות:

• Post, Page, and Attachment (Upload) Filters
• Comment, Trackback, and Ping Filters
• Category and Term Filters
• Link Filters
• Date and Time Filters
• Author and User Filters
• Blogroll Filters
• Blog Information and Option Filters
• General Text Filters
• Administrative Filters
• Rich Text Editor Filters
• Template Filters
• Registration & Login Filters
• Redirect/Rewrite Filters
• WP_Query Filters
• Media Filters
• Advanced WordPress Filters
• Widgets
• Admin Bar

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

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

כיצד להצמד להוקים או להסיר צימוד להוקים?

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

כיצד להצמד לפעולה

add_action( $hook, $function_to_add, $priority, $accepted_args );

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

הפרמטר priority הוא אופציונלי ומייצג מספר שלם בין 1 ל 999 הקובע את סדר העדיפויות של הפונקציות המוצמדות לאותו הוק ספציפי. ערך גבוה יותר ירוץ בשלב מאוחר יותר ולהפך. הפרמטר האחרון הינו פחות שימושי וקיים למצבים בהם אתם מעוניינים להעביר או לקבל מספר ארגומנטים.

לידיעתכם, פרמטר ה priority כברירת המחדל שלו הוא 10.

כיצד להצמד לפילטר

add_filter( $tag, $function_to_add, $priority, $accepted_args );

הפונקציה add_filter עובדת בצורה זהה כמו add_action, אך זכרו כי עבור פילטר – על הפרמטר function_to_add לקבל ערך ולהחזיר אותו בסוף הפונקציה.

כיצד להסיר צימוד להוקים

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

remove_action( $tag, $function_to_remove, $priority );

remove_filter( $tag, $function_to_remove, $priority );

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

דוגמאות שימוש בהוקים – וורדפרס

ישנם מעבר ל 200 הוקים בוורדפרס. כמובן שלתוספים ותבניות ישנם הוקים משל עצמם כך שמספר ההוקים הוא בעצם כמעט אינסופי. תנו מבט מטה ותראו מספר דוגמאות לשימוש בהוקים של וורדפרס ושל התוסף WordPress SEO by Yoast.

1. הוספת קישור לעמוד הבית בפוטר (footer)

<?php
/****** BEGIN HERE ******/
function add_footer_link() { ?> 
    <a href="https://savvy.co.il">Savvy.co.il - WordPress Developer &amp Designer</a>
<?php
}
add_action( 'wp_footer', 'add_footer_link' );

בדוגמא מעלה ניתן לראות פונקציה בשם add_footer_link המוצמדת להוק (פעולה) של וורדפרס בשם wp_footer. פעולה זו מאפשרת להוסיף קוד מסויים (במקרה שלנו קישור לעמוד הבית), במיקום של אותו הוק (מיקומו בפוטר).

2. שינוי אורך התקציר (excerpt)

function excerpt_length_example( $words ) {
    return 15;
}
add_filter( 'excerpt_length', 'excerpt_length_example' );

בדוגמא זו אנו נצמדים להוק (פילטר) בשם excerpt_length המספק לנו מספר (שלם) הקובע את מספר המילים שיופיע כשאשר משתמשים בפונקציה the_excerpt() בתבנית שלכם.

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

3. להצמד לשלב בו מפרסמים פוסט

function publish_post_tweet($post_ID) {
    global $post;
    // Code to send a tweet with post info
}
add_action('publish_post', 'publish_post_tweet');

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

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

4. להצמד לשלב בו מוסיפים נכסים (סקריפטים וקבצי CSS)

function themeslug_enqueue_style() {
	wp_enqueue_style( 'core', 'style.css', false ); 
}

function themeslug_enqueue_script() {
	wp_enqueue_script( 'my-js', 'filename.js', false );
}

add_action( 'wp_enqueue_scripts', 'themeslug_enqueue_style' );
add_action( 'wp_enqueue_scripts', 'themeslug_enqueue_script' );

אני מניח שראיתם משהו דומה לקוד הבא ברבים מהמאמרים בבלוג זה. הוא נמצא בשימוש רבות ולומדים אותו בשלב מאד מוקדם בעולם של פיתוח וורדפרס. במקרה זה אנו נצמדים להוק (פעולה) בשם wp_enqueue_scripts בכדי להוסיף נכסים – קבצי Javascript וקבצי CSS בצד לקוח (Frontend) בתבנית הוורדפרס שלכם. זוהי הדרך המועדפת להוסיף נכסים באתרי וורדפרס ונכונה יותר מאשר ״תכנות נוקשה״ הלא הוא hard coding.

זה המקום לציין, אם לא הייתי ברור – ניתן להצמיד כמה פונקציות שתרצו לאותו הוק!

5. הוספת מספר העמוד בכותרת המטא הנוצרת על ידי Yoast SEO

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

function change_yoast_title($title) {
   $paged = (get_query_var('paged')) ? get_query_var('paged') : 1;
   if ( is_paged() ) {
      return $title . ' - Page ' . $paged;
   }
   else {
      // first page of pagination
      return $title;
    }
}
add_filter('wpseo_title','change_yoast_title');

במקרה אמיתי זה, איש הקידום של אחת החברות להן אני מספק שירות, ביקש להוסיף בעמודים הממוספרים (paginated pages) של האתר את המילה Page ומספר העמוד בסופה של כותרת המטא (meta title) באותם עמודים.

לדוגמה, בעמוד שלוש יופיע Page 3 בסוף כותרת המטא וכנ״ל לגבי הכותרות בשאר העמודים הממוספרים, כל זאת כאשר בעמוד מספר אחד שינוי זה לא יתבצע. מכיוון ובמקרה של אותו אתר ספציפי כותרת המטא נוצרה באמצעות התוסף WordPress SEO by Yoast, נכון היה לחפש פילטר של Yoast המאפשר לבצע מודיפיקציה לכותרת העמוד.

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

6. הסרת כתובות קנוניות מעמודי תוצאות החיפוש באתר שלכם

פעולה שמקדמי אתרים יאהבו סביר להניח. בהנחה ואתם משתמשים ב Yoast SEO הפילטר הבא יסיר את הכתובת הקנונית (Canonical URL) מעמודי תוצאות החיפוש של וורדפרס:

function yoast_remove_canonical_search( $canonical ) {
	if( is_search() ) {
		return false;
	} else {
		return $canonical;
	}
}
add_filter('wpseo_canonical', 'yoast_remove_canonical_search');

יצירת הוקים (משלכם)

על מנת להשתמש בפונקציונליות של הוקים ליצירת הוקים משלכם, אינכם צריכים ליצור פונקציות מיוחדות – אתם יכולים להשתמש באותה פונקציה בה וורדפרס משתמשת בשם do_action.

1. הגדירו את ההוק שלכם

הוסיפו את הקוד הבא לקובץ functions.php (או לתוסף שלכם):

function custom_hook() {
   do_action('custom_hook');
}

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

2. הוסיפו את ההוק בתבנית שלכם

הוסיפו את הקריאה לפונקציה היכן שתרצו בתבנית שלכם:

<?php custom_hook(); ?>

ניתן  אגב פשוט להוסיף את do_action('custom_hook'); בתבנית ישירות.

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

3. הוסיפו את הפונקציה עצמה

כעת, בכדי להוסיף קוד משלכם במיקום זה עליכם להשתמש בקוד הבא:

if ( ! function_exists( 'your_function_name' ) ) {
    function your_function_name() {
    // Your custom code goes here
    }
    add_action( 'custom_hook', 'your_function_name' );
}

שימו לב כי עטפנו את הפונקציה ב if_function_exists()  בכדי למנוע שגיאות במקרה שכבר ישנה פונקציה בשם זה.

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

אז מה למדנו?

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

אם אהבתם את המדריך הרגישו חופשי לשתף ולספר מחשבות בתגובות מטה…  🙂