כתיבת מודול דרופל מבוסס פלגאין של jQuery

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

זו גם הזדמנות לחדד עוד יותר את כישורי כתיבת המודולים שלנו עבור דרופל 7, כשלמתחילים מומלץ לקרוא את המדריכים הקודמים שלי על כתיבת מודולים:

המדריך הראשון על כתיבת מודולים

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

הפלג-אין שנהפוך למודול דרופלי הוא totemticker שמבוסס על jQuery, וניתן לראות אותו בפעולה בתחתית דף הבית של האתר.

מבנה המודול

כל קבצי המודול יאוחסנו בתיקייה ששמה totemtocker, ובתוכה הקבצים הבאים:

totemticker.module- המודול עצמו שמטפל בממשק של הפלגאין עם דרופל.

totemticker.info- קובץ המידע על המודול.

totemticker.install- מאפשר את התקנת הטבלה שבה יאוחסנו הנתונים בבסיס הנתונים.

config.js- קובץ JavaScript, שמאפשר לקנפג את הפלגאין.

והתיקייה שתכיל את הפלגאין אותו נוריד בהמשך, שנקרא לה פשוט plugin.

קובץ totemticker.info

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

name = Totemticker
 
description = "Adds a Totemticker to the homepage with texts which can be supplied from the administration pages"
 
core = "7.x"
version = "7.x-1.0"
package = "Reshetech modules"
 
files[] = totemticker.module
files[] = totemticker.install
 
configure = admin/config/totemticker

קובץ totemticker.install

קובץ install כולל את ההוראות להוספת טבלה לבסיס הנתונים, עם התקנת המודול, באמצעות hook_schema(). בטבלה שני שדות:

ts_id שדה מספרי (type => int) הוא מזהה הטבלה, שנותן לנו primary_key לטבלה.

ts_text, שהוא שדה טקסט (type => text).

<?php
/**
 * Implements hook_schema().
 */
function totemticker_schema() {
  $schema = array();
 
  $schema['totemticker_source'] = array(
    'description' => 'Stores the text to be displayed in the totemticker.',
 
    'fields' => array(
      'ts_id' => array(
        'description' => 'The unique ID for each text.',
        'type' => 'serial', //Auto_Increment
        'not null' => TRUE,
      ),
      'ts_text' => array(
        'description' => 'The text to be displayed.',
        'type' => 'text',
        'not null' => TRUE,
      ),
    ),
 
    'primary key' => array('ts_id'),
  );
 
  return $schema;
}

קובץ totemticker.module

קובץ זה הוא ליבו של המודול, ומאפשר את הממשק בין דרופל ובין הפלגאין.

צעד 1: יצירת דף קונפיגורציה למודול ומתן הרשאות בהתאם

את הדף שמיועד למנהל האתר ניצור באמצעות hook_menu(), בכתובת admin/config/totemticker, כדי שיופיע בין הדפים המנהליים באתר. כדי להגן על הדף נשתמש ב-hook_permission(). זה הקוד:

/**
 * Implements hook_permission().
 */
function totemticker_permission() {
  return array(
    'access totemticker' => array(
      'title' => t('Acess totemticker configuration page'),
      'description' => t('Which role is allowed to access the configuration page'),
    ),
  );
}
 
/**
 * Implements hook_menu().
 */
function totemticker_menu () {
 
  // Makes "totemticker settings" appear on the administration configuration page.
  $items['admin/config/totemticker'] = array(
    'title' => 'Totemticker settings',
    'description' => 'The text to be displayed in the totem',
    'access arguments' => array('access totemticker'),
    'page callback' => 'drupal_get_form',
    'page arguments' => array( 'totemticker_source_config_form'),
    'type' => MENU_NORMAL_ITEM,
  );
 
  return $items;
}

צעד 2: שיבוץ טופס בדף

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

/**
 * Implements hook_form().
 */
function totemticker_source_config_form($form, &$form_state) {
 
  // Gets the texts which were inserted to the database. Each text on a new line.
  $output = variable_get('totemticker_config_array','');
 
  // The user inputs the text to be displayed in the totem.
  $form['totemticker_source']['source'] = array(
    '#title' => t('The text to be displayed in the totem'),
    '#type' => 'textarea',
    '#description' => t('Start each text in a seperate line'),
    '#default_value' => $output,
    '#required' => TRUE,
  );
 
  $form['submit'] = array(
    '#type' => 'submit',
    '#value' => t('Save'),
    '#submit' => array('totemticker_source_config_form_submit'),
  );
 
  return $form;
}

צעד 3: פונקציה שמכניסה את הנתונים שהזין המנהל למסד הנתונים

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

פקודות ה-sql מורצות באמצעות הפונקציה db_query, והתוצאה מאוחסנת במשתנה $result. כך נראית פקודת INSERT.

$result = db_query("INSERT INTO {totemticker_source} (ts_id, ts_text) VALUES (NULL, '{$text}')");

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

וזו הפונקציה המלאה:

/**
 * Form submit function inserts the data into the database.
 */
function totemticker_source_config_form_submit($form, &$form_state) {
  // The values that are passed from the form.
  $source = $form_state['values']['source'];
 
  // Creates an array of texts from the input we get from the form.
  $texts = totemticker_array_creator($source);
 
  // Deletes the old data from the database.
  db_query("DELETE FROM {totemticker_source}");
 
  // Insert each text to a seperate line in the database.
  foreach($texts AS $text){
    $result = db_query("INSERT INTO {totemticker_source} (ts_id, ts_text) VALUES (NULL, '{$text}')");
  }
 
  // Informs the administrator.
  drupal_set_message(t('The texts have been saved.'));
 
  // Queries for the data to be displayed.
  totemticker_query();
}

צעד 4: פונקציה שמסננת את הנתונים ומספקת מערך של טקסטים להזנה למסד הנתונים

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

/**
 * Creates an array of texts out of the the input that the administrator entered.
 */
function totemticker_array_creator($input){
  // Seperates the texts by new line, and create an $items array out of it.
  $items = explode(PHP_EOL, $input);
 
  // The array of texts that this function supplies.
  $texts = array();
 
  // Creates an array of texts out the $items array.
  foreach($items AS $item){
    // Saves the item's value after trimming it.
    $trimmed_item = trim($item);
 
    // Filters out unacceptable caracters.
    $regex = '/[^0-9a-zA-Zא-ת,.-\_?! ]/';
    $replace = '';
    $pregged_item = preg_replace($regex, $replace, $trimmed_item);
 
    // Skips empty values, and enters
    // the rest of the values into the $texts array.
    if($pregged_item != ''){
      // Adds the item to the texts array.
      $texts[] = $pregged_item;
    }
  }
 
  // Unsets the original array.
  unset($items);
 
  return $texts;
}

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

צעד 5: השאילתה ששולפת את הנתונים מבסיס הנתונים

בשלב זה, אנו שולפים את הנתונים, ומציגים אותם. השליפה ממסד הנתונים נעשית באמצעות SELECT.

בניית הנתונים לטובת הצגה בבלוק נעשית באמצעות המשתנה $tt_output, ובניית הנתונים להצגה בטופס האדמיניסטרציה נעשית באמצעות המשתנה $texts_in_rows.

המשתנים נשלחים לפונקציות שיטפלו בהם באמצעות variable_set, שמחזיר נתונים לשימוש מחוץ לפונקציה.

/**
 * Queries the database and selects the results that we want to display in the block and in the configuration form.
 */
function totemticker_query(){
  // Selects the texts from the database.
  $results = db_query("SELECT ts_text FROM {totemticker_source} ORDER BY ts_id LIMIT 0,6");
 
  // Gathers data into an array.
  $rows = array();
 
  foreach($results as $result){
    $rows[] = array(
      $result -> ts_text, //0
    );
  }
 
  // The following part does 2 things:
  // 1. Builds the HTML to be displayed in the block.
  // 2. Supplies an array of texts for the configuration form.
 
  // Builds the HTML.
  $tt_output = '';
 
  // Will be used to send data to the configuration form.
  $texts_in_rows = '';
 
  $tt_output .= '<ul id="vertical-ticker">';
 
  for($i = 0; $i < count($rows); $i++){
    // HTML for the block.
    $tt_output .= '<li>'. $rows[$i][0] .'</li>';
 
    // Array of texts for the configuration form.
    // Items are seperated by a new line.
    $texts_in_rows .= $rows[$i][0] . PHP_EOL;
  }
 
  $tt_output .= '</ul>';
 
  // Sends the HTML to the block.
  $totemticker_variable = variable_set('totemticker_variable', $tt_output);
 
  // Sends the array to be displayed in the configuration form.
  $totemticker_config_array = variable_set('totemticker_config_array', $texts_in_rows);
}

צעד 6: הצגה בבלוק

להצגה בבלוק, אנו זקוקים לשני הוקים:

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

hook_block_view(), מטפל בהצגת המידע עצמו. לכן הוא קולט את המידע ששלחנו באמצעות variable_set בצעד החמישי, באמצעות variable_get (המשתנה $output). בנוסף, מציג את המידע באמצעות הפריטים $block ['subject'], שמציג את הכותרת, ו-$block['content'] שמציג את התוכן.

/**
 * Implements hook_block_info().
 */
function totemticker_block_info() {
  $block['totem_ticker_block'] = array(
    'info' => t('Totemticker block for the homepage'),
    'cache' => DRUPAL_NO_CACHE,
  );
  return $block;
}
 
/**
 * Implements hook_block_view().
 */
function totemticker_block_view($delta = '') {
  $block = array();
  
  switch($delta){
    case 'totem_ticker_block':
      // Gets the variables.
      $output = variable_get('totemticker_variable','');
 
      // Presents the data in the block.
      $block['subject'] = 'Totemticker';
      $block['content'] = $output;
    break;
  }
  return $block;
}

צעד 7: נשלוט בדף שבו יפעל הפלג-אין

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

/**
 * Implements hook_init();
 */
function totemticker_init(){
 
  // Calls the query that selects the data to be displayed in the totem.
  if (drupal_is_front_page()) {
    // Adds custom CSS & JS to front page.
    drupal_add_css(drupal_get_path('module', 'totemticker') . '/plugin/style.totemticker.css');
 
    // The plugin's JS file.
    drupal_add_js(drupal_get_path('module', 'totemticker') . '/plugin/jquery.totemticker.min.js');
 
    // The plugin's configuration file.
    drupal_add_js(drupal_get_path('module', 'totemticker') . '/config.js');
 
    // Calls to the query that supplies the results to be displayed.
    totemticker_query();
  }
}

צעד 8: נוריד את הפלגאין ונכין אותו לשימוש

את הפלגאין עצמו ניתן להוריד מהקישור הבא:

Download totemticker jQuery plugin

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

jquery.totemticker.min

נשנה את שמו של הקובץ style.css, שהגיע עם הפלגאין ל- style.totemticker.css מפני שקבצים ששמם-style.css לא עובד במודולים דרופליים.

בתוך תיקיית המודל עצמו, ולא בתיקיית הפלגאין, נשבץ את קובץ ה-config.js, שמנהל את התנהגות הפלגאין. זה תוכנו:

(function ($) {
  $(document).ready(function() {
    $('#vertical-ticker').totemticker({
      row_height:'100px',
    });
  });
})(jQuery);

צעד 9: נתקין את המודול ונשבץ את הבלוק

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

לסיכום, אתם מוזמנים להוריד את קובץ המודול המלא המכווץ מהקישור המצורף:

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

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