آموزش ماژول نویسی در دروپال 7 - بخش هفت

آموزش ماژول نویسی در دروپال 7 - بخش هفت

ماژول نویسی دروپال بخش یک
ماژول نویسی دروپال بخش دو
ماژول نویسی دروپال بخش سه
ماژول نویسی دروپال بخش چهار
ماژول نویسی دروپال بخش پنج
ماژول نویسی دروپال بخش شش
ماژول نویسی دروپال بخش هشت

سیستم فیلدها در دروپال از چند بخش مجزا تشکیل می‌شه. پس از معرفی فیلد در ماژول به دروپال، این قابلیت ایجاد میشه که فیلد رو به یکی از موجودیت‌ها (entity) متصل کنیم، برای فیلد ویجت ورود داده تعیین کنیم (widget)، نحوه‌ی نمایش رو هم به یک display formatter بسپریم. هریک از این بخش‌ها hookهای مربوط به خودش رو داره.
هر فیلد در پایگاه داده در یک جدول مجزا ذخیره می‌شه. اما لزوما، این جدول، فقط یک مقدار رو ذخیره نمی‌کنه. یکی از دلایل خوبی که ممکنه نیاز باشه یک فیلد سفارشی تعریف کنیم، ذخیره همزمان چندین داده در یک رکورد از جدول به جای استفاده از چندین فیلد و جداول مجزاست. این کار می‌تونه باعث کارایی بیشتر و سازگاری بهتر با سیستم‌هایی باشه که بدون استفاده از API دروپال به پایگاه داده متصل می‌شن.

برای معرفی یک فیلد جدید، لازمه ابتدا ساختار جدول پایگاه داده رو در hook_field_schema تعریف کنیم. این تابع، آرایه‌ای از ساختار فیلدهای ماژول (که لزوما یکی نیستند) رو بر می‌گردونه و ساختاری مشابه با hook_schema که در مقاله‌های قبل بررسی کردیم داره. سپس، در hook_field_info، نام و مشخصات فیلد رو در آرایه‌ای که برمی‌گردونیم تعریف می‌کنیم. برای شناسایی شدن فیلد و نمایش در لیست فیلدهای موجود لازمه که حتما در هوک‌های field_widget_info و hook_formatter_info برای این فیلد، ویجت و display formatter تعریف کنیم. در دو hook آخری که نام بردیم، نام توابع مسئول نمایش داده‌های فیلد و ایجاد فرم ورود داده رو تعیین می‌کنیم.

توضیحاتی در مورد hookهای موجود:

  • hook_field_info: در این فیلد، ساختار کلی فیلد، نام فیلد، ویجت و display formatter پیش فرض که حتما باید تعیین بشوند رو مشخص می‌کنیم.
  • hook_field_schema: این هوک که بر خلاف سایر هوک‌ها در فایل .install قرار می‌گیره، آرگومانی شامل نام فیلد رو دریافت می‌کنه و بر اساس اون، باید ساختار پایگاه داده‌ی فیلد داده شده رو برگردونه.
  • hook_field_formatter_info: این هوک display_formatter هایی که از طرف ماژول موجود هستند و انواع فیلدی که این display formatter از اون‌ها پشتیبانی می‌کنه (مثلا فیلد تعریف شده در hook_field_info یا سایر فیلدهای تعریف شده در ماژول‌های دیگر مثل entity reference) رو مشخص می‌کنه. تنظیمات پیش‌فرض display_formatter هم در اینجا تعریف می‌شن.
  • hook_field_widget_info: ساختاری کاملا مشابه با hook_field_formatter_info داره اما ویجت رو تعیین می‌کنه.
  • hook_field_is_empty: با دریافت آرگومان‌هایی از API فیلد، مقداری TRUE یا FALSE تعیین کننده‌ی اینکه آیا فیلد حاوی مقدار هست یا نه رو برمی‌گردونه. فایده‌ی این کار، عدم ذخیره‌ی داده در پایگاه داده و یا عدم نمایش فیلد در صفحه‌ی نمایش محتواست در صورتی که فیلد خالی باشد.
  • hook_field_instance_settings_form: ساختار فرم تنظیمات هر نمونه از فیلد رو برمی‌گردونه (فیلدها پس از ساخته شدن برای اولین بار، می‌تونن در انواع محتوا و موجودیت‌های مختلف باز استفاده بشوند که به هرکدام یک نمونه می‌گیم). این تنظیمات به صورت اختصاصی برای همان نمونه ذخیره میشن. مسئولیت ذخیره‌ی تنظیمات به عهده‌ی خود Field API خواهد بود.
  • hook_field_settings_formساختار فرم تنظیمات هر فیلد رو برمی‌گردونه. این تنظیمات بین همه‌ی نمونه فیلدهای ساخته شده‌ی این فیلد مشترک خواهند بود.
  • hook_field_widget_form: فرم ویجت فیلد رو برمی‌گردونه
  • hook_field_formatter_settings_form - hook_field_widget_settings_form: هرکدام، فرم تنظیمات بخش مربوطه رو برمیگردونن.

لیست سایر هوک‌ها رو از اینجا می‌تونید ببینید.

برای تعریف فیلد وجود حداقل یک ویجت و display formatter الزامیه اما برعکس این مطلب درست نیست، یعنی برای تعریف یک display formatter لازم نیست حتما یک فیلد تعریف کنیم. در واقع می‌تونیم از فیلدهای موجود یکی رو انتخاب و به اون display formatter رو اختصاص بدیم.

مساله:

همونطور که اطلاع دارید، مرورگرهای وب، کاراکترهای newline یا "n\" رو یا کاملا نادیده می‌گیرند یا به کارکتر فاصله (space) تغییر میدهند. برای اینکه این کارکترها در صفحه ظاهر بشند، لازمه اونها رو به تگ‌های <br> در HTML تبدیل کنیم. با اینکه اینکار با RegEx امکان‌پذیره، PHP (متاسفانه یا خوشبختانه!) تابعی جداگانه برای اینکار داره: nl2br، که یک رشته‌ی متنی رو می‌گیره و تغییر newline_to_br رو اعمال می‌کنه.
فیلدهای longtext که در دروپال متن‌های طولانی رو ذخیره می‌کنند، قابلیت دریافت کاراکترهای newline رو دارند اما display formatter پیش‌فرض؛ همه‌ی متون رو به علت مشکل گفته شده در یک خط نشون می‌ده.

راه حل:

. در این بخش برای حل این مساله ماژولی برای یک display_formatter سفارشی برای فیلدهای longtext تعریف می‌کنیم. یک کار خوب، ایجاد شاخه‌ای در مسیر sites/all/modules به نام custom و قراردادن ماژول‌های سفارشی در این شاخه هست. این کار، تشخیص و نگهداری ماژول‌های سفارشی که از drupal.org دانلود نشده‌اند رو آسون‌تر می‌کنه. ماژول رو به این صورت تعریف می‌کنیم:

name = nl2br text formatter
description = A field display formatter which converts newline characters to HTML's BR tags
core = 7.x

فایل رو با نام nl2br_tf.info ذخیره می‌کنیم، مخفف nl2br_text_formatter، پس نام ماژول همان nl2br_tf خواهد بود.

برای معرفی display formatter هوک مربوطه رو در فایل .module پیاده‌سازی می‌کنیم:

<?php
/**
 * @file
 * nl2br text formatter main module file.
 */

/**
 * Implements hook_field_formatter_info().
 */
function nl2br_tf_field_formatter_info() {
  $formatter['nl2br_text_formatter'] = array(
    'label' => t('nl2br text formatter'),
    'field types' => array('text_long'),
  );

  return $formatter;
}

توضیحات:

  • نام display formatter رو nl2br_text_formatter که نام ماشینی هست در نظر گرفتیم.
  • برچسب رو در داخل تابع t قرار دادیم تا بعدا قابلیت ترجمه شدن داشته باشه.
  • انواع فیلدی که این display formatter از اون‌ها پشتیبانی می‌کنه، داخل یک آرایه قرار می‌گیره که در اینجا فقط فیلد text_long هست.

برای اینکه display formatter بتونه کارش رو انجام بده، هوک hook_field_formatter_view رو پیاده‌سازی می‌کنیم. هرگاه display formatter ماژول ما برای فیلدی در نظر گرفته شد (توسط مدیر سایت) و محتوایی شامل این فیلد به نمایش درمیاد، این هوک برای تولید اطلاعات نمایش داده شده صدا زده می‌شه. برای اضافه کردن این formatter به views یا نماها کار خاصی نباید انجام بدیم و به صورت خودکار صدا زده می‌شه. پیاده‌سازی این هوک به این صورت خواهد بود:

/**
 * Implements hook_field_formatter_view().
 *
 * Will replace all newline (\n) charachters to HTML <br> tags.
 */
function nl2br_tf_field_formatter_view(
    $entity_type, $entity, $field, $instance, $langcode, $items, $display) {

  $element = array();
  foreach ($items as $delta => $item) {
    $element[$delta]['#markup'] = nl2br($item['safe_value']);
  }

  return $element;
}

توضیحات:

  • قبل از هرکاری بهتره با استفاده از تابع dargs() مقادیر ارسالی به این هوک رو بررسی کنید.
  • این هوک آرگومان‌های مهمی دریافت می‌کنه که تعداد زیادی از اون‌ها بین اکثر هوک‌های مربوط به فیلد مشترک هستند: entity_type نوع موجودیتی که این فیلد به اون متصل شده، مثل node. و entity شامل خود موجودیت بارگذاری شده از پایگاه داده، field آرایه‌ای است از ساختار فیلدی که این display_formatter برای اون در نظر گرفته شده، instance ساختار این مورد خاص از فیلد که به این Bundle از entity متصل شده، langcode زبانی که فیلد جاری دارد، items مقادیز ذخیره شده در فیلد، display شامل حالت نمایش (محتوای کامل، teaser و ...).
  • langcode آرگومان مهمیست، از آنجایی که دروپال قابلیت‌های فوق‌العاده‌ای برای ترجمه‌ی محتوا داره و همه‌ی گره‌ها قابل ترجمه به زبان‌های مختلف هستند، در صورتی که فیلدی که بر روی اون عملیاتی انجام می‌دیم قابل ترجمه باشد، زبانی که باید برای نمایش انتخاب کنیم، در langcode قرار می‌گیره. توجه کنید که همه‌ی فیلدها قابل ترجمه شدن نیستند مثل فیلد entity reference، که در این صورت مقدار langcode برابر ثابت تعریف شده‌ی LANGUAGE_NONE که رشته‌ی 'und' هست خواهد بود.
  • فیلدها در دروپال می‌تونن حاوی چندین مقدار باشن، مقادیر مختل این فیلد از اندیس 0 تا اندیس n که نامشخصه در آرایه‌ی items قرار می‌گیرن.
  • برای نمایش داده‌ها از اندیس safe_value به جای value استفاده کردیم. چون منبع مقادیر موجود در فیلدها همیشه مشخص نیست، مثلا ممکن است به کاربران ناشناس اجازه‌ی ارسال مقالات رو داده باشیم، فیلدها مقادیر خودشون رو برای وجود داده‌های مخرب مثل تگ‌های script بررسی می‌کنند. استفاده نکردن از safe_value می‌تونه یک مشکل امنیتی حساب بشه.

مقداری که از hook_field_formatter_view بازگردانده می‌شود، یک آرایه‌ی قابل پردازش (Renderable array) خواهد بود. آرایه‌ی قابل پردازش در دروپال،‌ آرایه‌ای مشابه آرایه‌ی تعریف ساختار فرم‌هاست. یعنی شامل المان‌هاییست که با خصیصه‌های اختصاص یافته به اون‌ها امکان تبدیل برای نمایش در قالب HTML رو دارند. در مورد آرایه‌های قابل پردازش در دروپال اطلاعات بیشتری موجود هست. در این هوک، ما به ازای هر مقدار فیلد (توجه کنید که فیلد ارسالی به هوک می‌تونه حاوی چندین مقدار باشه، یعنی فیلد multi value باشه) در آرایه‌ی element$ یک اندیس برای آن مقدار در نظر می‌گیریم (همان delta) و محتوا رو در خصیصه‌ی markup# می‌ریزیم. در بخش‌های قبل دیدیم که محتوای خصیصه‌ی markup بدون هیچ تغییری، در صفحه نمایش داده خواهد شد. محتوایی که به markup اختصاص می‌دیم از فیلتر nl2br عبور کرده است و به درستی در صفحه نمایش داده خواهد شد.

اگر فیلدی از نوع long_text به محتوایی اضافه کنید، با رفتن به بخش display یا تنظیمات نمایش، می‌بینید که formatter ما (پس از فعال کردن ماژول) به لیست formatterهای موجود این فیلد اضافه شده. با انتخاب این formatter و نمایش یک محتوا خواهید دید فیلد به درستی به نمایش در می‌آید.

در بخش‌های بعدی مقاله به افزودن فرم تنظیمات و بررسی بیشتر فیلد می‌پردازیم.

شاد و موفق باشید.

تگ های مطلب: 

دسته بندی مطلب: 

دیدگاه‌ها

شمارش بازید از نود ها

با سلام، و خسته نباشید من دقیقا نمی دونستم سوالم رو در کدام قسمت باید می پرسیدم، ببخشید اگر جاش درست نیست، من می خواستم بودنم در دروپال چه ماژولی رو باید نصب کرد تا بشه تعداد نمایش هر نود رو شمرد؟ مثل همین چیزی که شما گذاشتین و نوشتین بازید:1233 چطور میشه این رو برای هر نود فعال کرد که بازدید از هر نود را بشمارد؟ ممنون میشم جوابم رو بدید.

یک ماژول توی هسته دروپال هست

یک ماژول توی هسته دروپال هست به نام Statistics شما با نصب اون میتونید آمار بازدید رو داشته باشید

تعداد بازدید برای هر نود

من این ماژولا نصب کردم اما وقتی به صفحه ی هر نود میرم چیزی نیست آیا باید کار خاصی انجام بدم

فروش درب چوبی ساختمان

خیلی ممنون از سری آموزش هاتون اگه امکانش هست ماژول نویسی تو وردپرس رو هم برامون آموزش بدید تشکر

مطلب خوبی قرار دادید موفق

مطلب خوبی قرار دادید موفق باشید

کاغذدیواری

عالی بود ممنون از سایت مفیدتون

دیدگاه جدیدی بگذارید

آخرین ارسال ها

محتواهای محبوب

درباره ما

Author
اینجا دروپال یعنی همه چیز. در مورد دروپال صحبت میکنیم. ماژول هامون رو به اشتراک میزاریم در مورد قالب دروپال ، فروشگاه دروپال، دروپال فارسی و تاریخ شمسی دروپال صحبت میکنیم و هرچیزی که در مورد طراحی سایت با دروپال میدونیم به هم انتقال میدیم. دروپالیون یک سایت شخصی نیست. ما دست همه کسانی که برای پیشرفت دروپال تلاش میکنند رو میفشاریم و با آغوش باز اونها رو در این سایت میپذیریم.

تماس با ما

با ما تماس بگیرید.

logo-samandehi