ایجاد بلوک توسط ماژول نویسی

برای ایجاد بلوک در دروپال دو راه وجود دارد:

1. ایجاد بلوک در صفحه ی مدیریت بلوک ها (admin/build/blocks) که به این نوع بلوک ها، بلوک های سفارشی می گویند
2. ایجاد بلوک توسط برنامه نویسی در ماژول ها (که به این نوع بلوک ها، بلوک های default می گویند)

برای ایجاد یک بلوک توسط ماژول، باید هوک block را در ماژول تعریف کنیم. طریقه ی تعریف هوک block به صورت زیر است:

function hook_block($op = 'list', $delta = 0, $edit = array())

این تابع، دارای 3 تا آرگومان است که در زیر هر یک از آن ها را توضیح می دهم.

آرگومان $op

دروپال هنگامی که می خواهد در خصوص بلوک ها کاری انجام دهد یا اطلاعاتی به دست بیاورد، هوک block را اجرا می کند. و بسته به این که چه کاری می خواهد انجام دهد و چه اطلاعاتی را می خواهد دریافت کند، مقدار متفاوتی را به آرگومان $op ارسال می کند.

در زیر مقادیری که ممکن است به $op ارسال شود را لیست می کنم:

بنابر این، باید در تعریف هوک block، بررسی کنیم که آرگومان $op چه مقداری دارد. تا به این وسیله بفهمیم که دروپال از این هوک چه انتظاری دارد و کار مورد نظر را انجام دهیم.
برای این منظور، معمولا باید یک دستور switch را به کار ببریم و مقادیر $op را در آن تست کنیم:

function MYMODULE_block($op = 'list', $delta = 0, $edit = array()) {
  switch ($op) {
    case 'list':
     
      break;
    case 'configure':
     
      break;
    case 'save':
     
      break;
    case 'view':
     
      break;
  }
}

1 - لیست کردن بلوک ها ('list')

هنگامی که دروپال می خواهد لیست بلوک ها را به دست آورد، هوک block را با آرگومان $op و مقدار 'list' فراخوانی می کند. در این حالت، هوک block باید یک آرایه برگرداند که شامل لیست بلوک هایی که قرار است تعریف کنیم باشد.
این آرایه، یک آرایه ی تو در تو کلید/مقدار است. کلید ها در این آرایه $delta می باشند (یک شناسه ی منحصر به فرد بین تمام بلوک هایی که این ماژول تعریف می کند)
مقادیر هر کلید در این آرایه، خود یک آرایه کلید/مقدار دیگر است که خصوصیات بلوک را مشخص می کند. کلید های زیر وجود دارند:

• 'info'
  این مقدار ضروری است. و یک مقدار ترجمه شده است که در صفحه ی مدیریت بلوک ها برای عنوان بلوک به مدیر سایت نشان داده می شود.
• 'cache'
  چگونگی cache شدن بلوک را مشخص می کند. مقادیر زیر وجود دارد:
  
  • BLOCK_NO_CACHE : بلوک اصلا cache نشود.
  • BLOCK_CACHE_PER_ROLE : بلوک برای هر نقش کاربری به صورت جداگانه cache شود.
  • BLOCK_CACHE_PER_USER : بلوک برای هر کاربر عضو سایت جداگانه cache شود (برای سایت هایی که تعداد زیادی کاربر دارد توصیه نمی شود.)
  • BLOCK_CACHE_PER_PAGE : بلوک برای هر صفحه از سایت جداگانه cache شود.
  • BLOCK_CACHE_GLOBAL : بلوک برای کل سایت و همه ی اعضا، فقط یک بار cache شود.
• 'status'
  مشخص می کند که آیا بلوک به طور پیش فرض (بعد از فعال شدن ماژول ما) فعال باشد یا خیر (TRUE یا FALSE) مقدار پیش فرض FALSE است.
• 'region'
  ناحیه ی پیش فرضی که بلوک در آن قرار میگیرد. البته بلوک می تواند بعدا توسط مدیریت سایت به یک ناحیه دیگر منتقل شود. این مقدار فقط به شرطی موثر است که status هم برابر TRUE باشد؛ اگر بلوک غیر فعال باشد، region برابر با 'None' قرار میگیرد.
  توجه کنید که نام region ها (ناحیه ها) بستگی به theme سایت دارد.
• 'weight'
  مشخص کننده ی ترتیب چینش بلوک ها در یک ناحیه می باشد. هرچه weight بیشتر باشد، بلوک سنگین تر می شود و در راستای عمودی به سمت پایین می آید و در راستای افقی به سمت راست متمایل می شود. (البته خیلی هم ربطی به راست و چپ و بالا و پایین ندارد. منظور این است که هرچه weight بیشتر باشد، بلوک دیرتر render می شود و در سورس HTML صفحه، بلوک پایین تر می آید. موقعیت ظاهری بلوک به عوامل دیگری مثل css و ... هم بستگی دارد)
  مقدار پیش فرض weight برابر صفر است.
• 'pages'
  مشخص می کند که به طور پیش فرض، بلوک در چه صفحاتی باید قابل رویت باشد. مقدار پیش فرض آن یک رشته ی تهی "" است.
  این مقدار، باید شامل مسیر های دروپالی باشد که با کاراکتر جداکننده ی خط از هم جدا شده اند. کاراکتر * یک wildcard است. به عنوان نمونه مسیر های زیر را مثال می زنم:
  'blog' برای صفحه ی اصلی وبلاگ (?q=blog) و 'blog/*' برای همه ی صفحات وبلاگ های شخصی.
  '<front>' برای صفحه ی اصلی به کار می رود. برای اطلاعات بیشتر به مستندات تابع drupal_match_path() مراجعه کنید.
• 'custom'
  TRUE یعنی این یک بلوک سفارشی است و FALSE یعنی این بلوک توسط یک ماژول ایجاد شده است. (؟؟)
• 'title'
  عنوان پیش فرض بلوک (؟؟)

2 - تنظیمات اختصاصی بلوک ('configure')

هنگامی که دروپال می خواهد فرم پیکربندی تنظیمات بلوک را نمایش دهد، هوک block را با آرگومان $op و مقدار 'configure' فراخوانی می کند.
در این حالت، در هوک block باید یک آرایه برگردانیم که تعریف فرم تنظیمات بلوک است. این آرایه از نوع form definition array می باشد (به مستندات Form API یا FAPI مراجعه کنید)
مقداری که در این جا برگردانده می شود، با فرم پیش فرض تنظیمات بلوک ترکیب می شود و به این ترتیب به ما اجازه می دهد که فرم تنظیمات بلوک را گسترش دهیم و عناصر مورد نظر مان را به آن اضافه کنیم.
هنگامی که فرم تنظیمات بلوک را گسترش می دهید، لازم دارید که کد لازم برای ذخیره ی تنظیمات بلوک را نیز در $op='save' بنویسید. (قسمت زیر را ببینید.)

3 - ذخیره کردن تنظیمات اختصاصی بلوک ('save')

هنگامی که فرم پیکربندی تنظیمات اختصاصی بلوک submit می شود و دروپال می خواهد تنظیمات را ذخیره کند، هوک block با آرگومان $op و مقدار 'save' فراخوانی می شود.
در این حالت، باید مقادیر ارسال شده از فرم پیکربندی بلوک را (که توسط عملیات configure ایجاد کردیم) ذخیره کنیم. این مقادیر در آرگومان $edit وجود دارند.
در این عملیات 'save' ، لازم نیست چیزی را برگردانیم.

4 - نمایش بلوک ('view')

هنگامی که دروپال می خواهد یک بلوک را به کاربر نمایش دهد، هوک block را با آرگومان $op و مقدار 'view' فراخوانی می کند.
در این عملیات، باید یک آرایه شامل title و content بلوک را برگردانیم.

آرگومان $delta

از آن جایی که هر ماژولی می تواند چند تا بلوک را تعریف کند، یک شناسه ی منحصر به فرد به نام $delta وجود دارد که وجه تمایز بلوک های ایجاد شده توسط یک ماژول است. مثلا ماژول MyModule می تواند 2 تا بلوک تعریف کند که دلتای بلوک اولی برابر 'first' و دلتای بلوک دومی برابر 'second' باشد
هنگامی که دروپال هوک block را با هر یک از مقادیر $op زیر فراخوانی می کند:

$op = 'configure'
$op = 'save'
$op = 'view'

آرگومان $delta مشخص می کند که این عملیاتی که دارد انجام می گیرد، در مورد کدام بلوک می باشد.
مثلا در مثال قبلی، هنگامی که تنظیمات بلوک 'first' در حال ذخیره شدن است، هوک block با آرگومان $op برابر 'save' و آرگومان $delta با مقدار 'first' فراخوانی می شود.

توجه کنید که هنگامی که آرگومان $op برابر 'list' است، مقدار آرگومان $delta نادیده گرفته می شود و اهمیتی ندارد. زیرا عملیات 'list' خودش دارد بلوک ها و delta ی آن ها را تعریف می کند.

آرگومان $edit

هنگامی که آرگومان $op بربر 'save' است (در عملیات save قرار داریم) ، آرگومان $edit شامل مقادیر ارسال شده توسط فرم پیکربندی بلوک می باشد. (به مستندات FAPI مراجعه شود.)