כיצד לבנות מודול בדרופל 7? - חלק א

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

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

המרכיבים ההכרחיים בכל מודול

בכל מודול הכרחי שיהיו שלושת המרכיבים הבאים:

1. תיקייה עם שמו של המודול. לדוגמה: , cache_flash

2. קובץ .info עם שמו של המודול. לדוגמה: , cache_flash.info

3. קובץ .module עם שמו של המודול. לדוגמה: . cache_flash.module

קובץ info

לקובץ ה-.info נוסיף את המידע הבא, שרובו יופיע בדף המודולים:

name = Cache Flash
description = "Adds a URL with flush all caches option"
core = 7.x
version = "7.x-1.0"
package = My Modules
files[] = cache_flash.module

name הוא שמו של המודול, ונהוג להתחיל כל מילה באות גדולה.

description הוא תיאור קצר של המודול בין מירכאות.

core זו גרסת הליבה של דרופל, ובמקרה זה דרופל שבע.

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

package זו החבילה שאליה משתייך המודול, ובדף רשימת המודולים כל המודולים ששייכים לחבילה יופיעו ביחד באותו חלון.

files הוא מערך שכולל בתוכו את כל קבצי המודול שאינם info. במודול המאוד פשוט שבדוגמה, הקובץ הנוסף שמו cache_flash.module.

קובץ module ו-hooks

לקובץ המודול נוסיף את הפונקציונליות שבה אנחנו מעוניינים. לשם כך, צריך להכיר את ה-API של דרופל, שהכניסה אליו מהקישור הבא:

Drupal developing API

בבסיסו, דרופל כתוב ב-PHP, אבל לרוב, נשתמש בשכבה נוספת של הוקים (hooks) שמספק ה-API של דרופל. ההוקים (ווים) מאפשרים לנו להתממשק (מלשון ממשק) עם ליבת דרופל, ועם המודולים השונים.

hook_menu() מגדיר דף ו-URL

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

<?php
/**
 * Implements hook_menu().
 */
function cache_flash_menu () {
  $items = array();
  $items['admin/cache_flash'] = array(
    'title' => 'Cache Flusher',
    'page callback' => 'cache_flash_page',
    'access arguments' => array('access cache_flash'),
    'type' => MENU_NORMAL_ITEM,
  );
 
  return $items;
}

3 השורות הראשונות הם הערה בסגנון doxygen, שאומרת שאנחנו מיישמים את ההוק הספציפי.

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

function my_module_hook_name

ובדוגמה שלנו ההוק נראה כך:

function cache_flash_menu() {
 
}

בתוך ההוק, בין סוגריים מסולסלים, אנחנו יוצרים מערך אסוציאטיבי $items עם כתובת ה-URL של הדף ['admin/cache_flash'].  במקרה זה אנחנו מפנים לכתובת שצריכה להיות כלולה בתוך תפריט האדמיניסטרציה, ולכן "התיקייה" היא admin, והכתובת של הדף עצמו היא cache_flash.

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

title – זו הכותרת שתופיע על הקישור בתפריט האדמיניסטרציה,

page callback - קורא לפונקציה שמייצרת את הדף עצמו,

access arguments – מגדיר מערך שניצור באמצעות hook_permission() כדי לשלוט בהרשאות לשימוש בתכונה שמוסיף המודול.

קיימות אפשרויות נוספות, ועליהם מומלץ לקרוא בדף שמוקדש ל-hook menu בדרופל העולמי:

hook menu API

type - סוג הדף שיצרנו. במקרה זה, יצרנו דף רגיל.

בסוף נפעיל את המערך שיצרנו באמצעות:

return $items;

hook_permission() מגדיר הרשאות גישה

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

/**
 * Implements hook_permission().
 */
function cache_flash_permission() {
  return array(
    'access cache_flash' => array(
      'title' => t('Acess to cache_flash'),
      'description' => t('Which role is allowed to flush the caches.'),
    ),
  );
}

כדאי לשים לב, ששמו של המערך 'access cache_flash' תואם בדיוק של את שמו של המערך ב-'access arguments' ב-hook_menu().

ועכשיו כשנכנס לדף ההרשאות, באמצעות People >> Permissions, נוכל לתת את ההרשאה, רק למי שאנחנו רוצים. כך זה נראה בדף ההרשאות:

הפונקציה שמייצרת את הדף

ראינו למעלה, ש-hook_menu() קורא לפונקציה שמייצרת את הדף. בפונקציה שמייצרת את הדף, נשלב HTML ופונקציה שמנקה את המטמונים.

כך ייראה הקוד:

/**
 * The page with the functionality that flushes all the caches.
 */
function cache_flash_page() {
  //The function that flushes the caches.
  drupal_flush_all_caches();
 
  //Inform the user.
  drupal_set_message('All the caches have been flushed.');
 
  //Some markup to fill the page.
  $items['flash_cache_text'] = array(
    '#markup' => '<p>' .t('Thank you for using this module') .'</p>',
  );
 
  return $items;
}

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

drupal_set_message() מציג הודעה למשתמש.

וכל החלק האחרון, מייצר את ה-HTML.

כך נראה הדף שייצרנו באמצעות המודול כשנכנס אליו מתפריט המנהל באתר:

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

קובץ המודול המלא

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

<?php
/**
 * Implements hook_menu().
 */
function cache_flash_menu () {
  $items = array();
  $items['admin/cache_flash'] = array(
    'title' => 'Cache Flusher',
    'page callback' => 'cache_flash_page',
    'access arguments' => array('access cache_flash'),
    'type' => MENU_NORMAL_ITEM,
  );
 
  return $items;
}
 
/**
 * Implements hook_permission().
 */
function cache_flash_permission() {
  return array(
    'access cache_flash' => array(
      'title' => t('Acess to cache_flash'),
      'description' => t('Which role is allowed to flush the caches.'),
    ),
  );
}
 
/**
 * The page with the functionality that flushes all the caches.
 */
function cache_flash_page() {
  //The function that flushes the caches.
  drupal_flush_all_caches();
 
  //Inform the user.
  drupal_set_message('All the caches have been flushed.');
 
  //Some markup to fill the page.
  $items['flash_cache_text'] = array(
    '#markup' => '<p>' .t('Thank you for using this module') .'</p>',
  );
 
  return $items;
}

במדריך הבא נסביר כיצד לשלב בלוק וטופס במודול.

אהבתם? לא אהבתם? דרגו!

0 הצבעות, ממוצע 0 מתוך 5 כוכבים