ساخت ماژول جدید در مودل
NEWMODULE Documentation

 

آموزش موجود که در ادامه با هم شروع می کنیم در مورد جدیدترین مطلب منتشر شده در مودل است که ساخت ماژول جدید را آموزش می دهد. این آموزش طبق گفته داکیومنت رسمی مودل در حال پیشرفت است و ممکن است اصلاحات یا تغییراتی در آن به وجود بیاید ، و از کاربران مودل تقاضا شده است در صورت وجود انتقاد، پیشنهاد در مورد این مطلب به انجمن های بحث مرتبط با این موضوع در moodle.org بپیوندند و یا در این قسمت نظرات مربوط به این نوشته کامنت خود را قرار دهند.

ساخت ماژول جدید

بیاین شروع کنیم

محتوای پوشه Base ماژول

برای ساختن ماژول جدید در مودل یک بسته به نام NEWMODULE ایجاد کرده ایم :

https://github.com/moodlehq/moodle-mod_newmodule ( ورژن ۲٫x مودل)

https://github.com/moodlehq/moodle-mod_newmodule/tree/MOODLE_19_STABLE ( ورژن ۱٫۹ مودل)

 

توجه کنید که این آموزش برای نسخه ۱٫۹ نوشته شده است و برای Moodle 2.x هنوز آپدیت نشده است. با این حال تا زمان آپدیت این ورژن بیشتر مواردی که گفته می شود برای این ورژن نیز قابل پیاده سازی است.

برای درک بهتر بیاین از مواردی که در پوشه newmodule می توانیم پیدا کنیم شروع کنیم :

http://download.moodle.org/plugins19/mod/NEWMODULE.zip

مسیری که شما در آن مسیر هر فایل را پیدا می کنید درست ترین مسیر است. بنابراین مسیر فایل ها و پوشه ها را در این بسته تغییر ندهید.

در ابتدا، در داخل پوشه db، شما فقط می توانید  install.xml و upgrade.php را پیدا کنید.اما هرچه زودتر شروع به اضافه کردن فایل جدید“access.php” کنید.

db/install.xml

فایل db/install.xml  برای نوشتن xml است که جداول مورد نیاز ماژول را توصیف می کند. جداول حداقل دو تا هستند، که برای بار اول به نام همان  ماژول نامیده می شود، و برای بار دوم با نام “log_display” خوانده می شوند.این کار یک دستورالعمل دقیق دارد که شما می توانید با ویرایش یکی از چند نمونه که می توانید در داخل ماژول moodle پیدا کنید یاد بگیرید. در نهایت تنها چیزی که باید مراقب باشد <<previous>> <<next>> اتصال بین جداول و فیلدها است. این فایل یک فایل اجباری است که در آن شما باید ساختار جداول مورد استفاده در مورد ماژول را بنویسید. جدول “log_display” یکی از جداولی است که در آن شما درخواست می کنید همه “actions”هایی که می خواهید به log ماژولتان اضافه شود را لیست کند.

 

db/upgrade.php

db / upgrade.php فایلی است که شما هر بار که نیاز به تغییر ساختار جداول ماژول خود داشتید در آن می نویسید. برای یادگیری نحوه نوشتن این فایل، لطفا به نمونه هایی که  در فایل خود پیدا می کنید مراجعه کنید.

 

icon.gif

یک آیکون ۱۶*۱۶ پیکسل است که هر نمونه از ماژول شما را در قالب یک course شناسایی می کند.

 

index.php

index.php یک صفحه برای لیست تمام موارد فانکشنالیتی است که ماژول  در یک دوره (course) فراهم می کند.

 

lang

lang پوشه ای است که برای بسته های زبان تعبیه شده است. بسته ی ماژول زبان شامل یک پوشه به نام “xx_utf8” است که خود شامل یک پوشه به نام “help” و یک فایل زبان با نام همان ماژول است. xx نام دو کاراکتر طولانی زبان است، بعنوان مثال en، de، es، it، fr و غیره. هر فایل زبان به یک زبان خاص اختصاص داده شده است. پوشه lang می تواند شامل بسته های زبان به همان اندازه که توسط مترجمان مختلف ارائه شده است ، باشد.

پوشه /lang / xx_utf8 / help  حاوی تمام فایل های راهنمایی است که می خواهید برای ماژول خود ارائه کنید. بعبارتی برای لینک کردن یک فایل help از درون کد صفحات ماژولتان از

mform->setHelpButton in mod_form.php$ استفاده می کنید و برای سایر موارد از کد زیر استفاده می شود:

 

lib.php

lib.php فایل از قبل با توابع “core” نوشته شده است که مورد نیاز هر یک از ماژول ها است. تقریبا تمام توابع newmodule در این فایل می آیند. تمام توابع باید یک نام داشته باشند که با newmodule_ شروع می شود. این فایل باید تنها شامل توابع استاندارد API مودل، که به ماژول اجازه می دهد در Moodle به صورت یکپارچه کار کند باشد.

تمام توابع خاص newmodule  برای پیاده سازی عملکرد منطقی ماژول باید در کلاس های اتولود داخلی کلاس ها در دایرکتوری  newmodule / classes پیاده سازی شوند. این کار به صرفه جویی در حافظه هنگامی که مودل در حال انجام actionهایی در همه ی ماژول ها است، کمک می کند. برای اطلاعات بیشتر به بارگزاری اتوماتیک کلاس ( Automatic class loading) مراجعه کنید.

برای نامگذاری توابع در lib.php قوانینی به این شرح وجود دارد:

در lib.php بعضی از جزئیات تنها در بالای هر تابع آورده می شود.

نمونه ای از توابع اجباری:

ماژول نمونه مدیریت ویرایش فرم ، که می توان از course/mod.php یا course/modedit.php فراخوانی شود.

  • (function newmodule_add_instance($newmodule

این تابع بعد از اینکه یک معلم ویرایشگر یک نمونه از  newmodule را ایجاد می کند، اجرا می شود.

  • (function newmodule_update_instance($newmodule

این تابع بعد از اینکه یک معلم ویرایشگر یک نمونه از  newmodule را ویرایش می کند، اجرا می شود.

  • (function newmodule_delete_instance($id

این تابع بعد از اینکه یک معلم ویرایشگر یک نمونه از  newmodule را حذف می کند، اجرا می شود.

  • ()function newmodule_user_outline
  • (function newmodule_user_complete($course, $user, $mod, $newmodule
  • (function newmodule_print_recent_activity($course, $isteacher, $timestart
  • ()function newmodule_cron

مراقب این توابع باشید. برخلاف سایر توابع، این توابع با عبور دادن رکورد newmodule$ فراخوانی نمی شوند. این بدین معنی است که این تابع که توسط هسته کرون مودل فراخوانی می شود ، باید قبل از عملیات هر شناسه نمونه ای newmodule را جستجو کند.

نگران نباشید، حتی اگر شما بیش از یک نمونه از ماژول خود در میان دوره های moodle داشته باشید، این تابع تنها یک بار اجرا می شود.

  • (function newmodule_get_participants($newmoduleid
  • (function newmodule_scale_used($newmoduleid, $scaleid  
  • (function newmodule_scale_used_anywhere($scaleid
  • ()function newmodule_install
  • ()function newmodule_uninstall

توابع بیشتری باید اضافه شود:

  • (function newmodule_reset_course_form_definition(&$mform
  • (function newmodule_reset_course_form_defaults($course
  • (function newmodule_reset_userdata($data

این سه توابع مسئول فرایند ریست newmodule در طول فرایند کلی ریست course هستند. لطفا برای درک بهتر این توابع به مثال های موجود در mod / data / lib.php یا به mod / feedback / lib.php مراجعه کنید.

توابع دیگری که می توانند به lib.php اضافه شوند عبارتند از:

  • (function newmodule_get_shortcuts($defaultmodule

لیستی از آیتم هایی که باید به “Activity chooser”  بجای گزینه های پیش فرض اضافه شود را برمیگرداند. این تابع در mod/lti/lib.php استفاده می شود.

  • function newmodule_check_updates_since

بررسی می کند که آیا ماژول آپدیتی برای تاثیر بر کاربرفعلی در زمانی که از آن گرفته، دارد یا نه. برای دیدن کد نمونه به mod/assign/lib.php یا mod/forum/lib.php یا mod/quiz/lib.php مراجعه کنید.

اگر ماژول شما از تقویم استفاده می کند، باید موارد زیر را در lib.php در نظر داشته باشید.

  • (function newmodule_refresh_events($courseid, $instance = null, $cm = null

این تابع تمام رویدادهای تقویم مرتبط با تغییراتی که در فعالیت انجام می شود ( مانند تغییر نام ) را اپدیت می کند.

 

mod_form.php

mod_form.php فایلی است که  فرمی را که شما در زمان ایجاد یا زمان ویرایش ماژول نمونه ، گرفته اید توصیف می کند.

تنها یک تعریف کلاس وجود دارد، که موجب می شود کلاس moodleform_mod از /course/moodleform_mod.php گسترش یابد.

نحو اضافه کردن عناصر فرم جدید بسیار ساده است و با مطالعه فایل خیلی ساده می توانید  آن را بر اساس نیاز خود تغییر دهید. نحو استفاده از آن را می توانید در lib / formslib.php_Form_Definition یاد بگیرید.
این فایل فقط از /course/modedit.php استفاده می کند.
این بخش با یک فراخوانی تابع از moodleform_mod به ارث رسیده است که مسئول بخش های مشترک ماژول در انتهای صفحه نمونه ویرایش newmodule شما است. این بخش مربوط با گروه ها، نتایج، نمرات، دیدگاه ها و غیره است. این کد را می توان بوسیله تنظیم ارسال شیء به آن سفارشی کرد:

نکات بیشتر در مورد  این فایل:

  • هنگامی که شما فرم ارسال شده توسط این فایل را ارسال می کنید، ماژول شما این تابع را اجرا می کند: newmodule_add_instance یا newmodule_update_instance .که هر دو از قبل در lib.php (در بالا توضیح داده شد) نوشته شده است.
  • به نظر می رسد که چک باکس ها در فرم نمونه ویرایش کار نمی کنند.برای آزمایش آن، لطفا پارامتر  newmodule$ را داخل تابع newmodule_update_instance  با یک پرینت ساده از newmodule$ تایید کنید.
  • شما متوجه خواهید شد که حتی با انتخاب یا عدم انتخاب چک باکس در نمونه فرم ویرایش newmodule، مقدار مربوطه در آرایه تغییری نخواهد کرد. این یک خطا نیست، اما حداقل ایراد کد است. شما متوجه خواهید شد که همه کارها با اضافه کردن  یک کد ساده مثل این در ابتدای هر دو توابع خوب انجام خواهد شد:

 

README.txt

فایلی است که در مورد آنچه که newmodule شما انجام می دهد، شامل دستورالعمل هایی برای شروع استفاده از افزونه ها و یا مانند مراحل نصب انها صحبت می کند. اگر قصد شما این باشد که ماژول خود را در Github منتشر کنید، شما باید فایل README.md را فراخوانی کنید و آن را به روش Markdown همگام سازی کنید.

 

thirdpartylibs.xml

لیستی از همه کتابخانه های ۳ قسمتی بهمراه یک افزونه.

بعنوان مثال:

جایی که location یک مسیر نسبی به دایرکتوری یا فایل library است. لطفا توجه داشته باشید که license باید همیشه با GNU GPL 3 هماهنگ باشد.

 

version.php

فایل version.php فایل بسیار ساده و به همان اندازه بسیار مهم است.

برای درک این اهمیت، شما باید بدانید که دسته ای از اقدامات وجود دارد که مودل برای newmodule  انجام می دهد اما تنها (تنها با یک استثنا) در زمان نصب newmodule. آنها جدول های ویرایش db و بارگزاری قابلیت ها هستند. اگر در طول زمان توسعه ماژول خود  (که قبلا در محیط توسعه خود نصب کرده اید یا اینکه قبلا با کاربران راه دور به اشتراک گذاشته اید) نیاز به تغییر ساختار جداول newmodule خود پیدا کردید یا نیاز به تغییر قابلیت استفاده شده توسط newmodule خود داشتید، باید moodle را مجبور به ویرایش جداول و قابلیت بارگذاری مجدد کنید.

این کار به طریق زیر انجام می شود:

  1. اضافه کردن کد مناسب در newmodule / db / upgrade.php (برای انجام این کار از XMLDB استفاده کنید همانطور که در زیر همین صفحه بیان شده است)
  2. بالا بردن ورژن newmodule در فایل version.php
  3. دیدن صفحه نوتیفیکیشن از نصب moodle شما

 

view.php

این فایل اولین کد اجرا شده ماژول شماست. با انتخاب پیوند نمونه از ماژول، کد newmodule/view.php اجرا می شود.

 

برخی از فایل های مهم فراموش شده

چهار فایل وجود دارد که در بسته newmodule وجود ندارد و در ۹۰٪ از موارد شما آن ها را به newmodule خود اضافه می کنید.

  • access.php : دومین فایل access.php است که باید در داخل فولدر  / newmodule / db ذخیره شود. در این فایل شما تمام قابلیت های مورد استفاده توسط newmodule خود را بارگذاری می کنید که موجب می شود در زمان نصب یا آپگرید بارگذاری شود. برای یادگیری نحو تنظیم قابلیت ماژول، لطفا این مطلب را مطالعه کنید.
  • settings.php : سومین فایل مهم فراموش شده settings.php است که باید به فولدر /newmodule اضافه شود که فرمی را که از طریق مسیر زیر قابل دسترسی است را توصیف می کند :Site Administration block -> Modules -> Activities -> <<your newmodule name>> . این فرم تنظیمات کلی برای newmodule شما را در شیء CFG$ ذخیره می کند .به همین جهت، به شدت توصیه می شود که تنظیمات کلی newmodule خود را با نام هایی که با “newmodule_” آغاز می شود، انجام دهید. این فایل زمانی که تنظیماتی وجود ندارد که وابسته به نمونه باشد، مفید است. به عنوان مثال، اگر newmodule شما یک تلفن را شبیه سازی کند، احتمالا شما شماره تلفن خود را در فرم تنظیمات newmodule سایت وارد می کنید به جای اینکه هربار که نمونه جدیدی از newmodule خود را به یک دوره اضافه کنید، شماره تلفن ها را تایپ کنید.در همین راستا، برای مراجعه به شماره تلفن های موجود در درون newmodule تان باید به از CFG->newmodule_telephonenumber$ استفاده کنید.
  • backuplib.php : به طور مستقیم در پوشه newmodule، شما نیاز به اضافه کردن backuplib.php را دارید که مسئول پشتیبان گیری از هر نمونه ماژول و log آن است.برای یادگیری نحوه کد نویسی آن،  از برخی از ماژول های دیگر که از آن استفاده کرده اند شروع و آن را بخوانید.
  • restorelib.php : مجددا در پوشه newmodule، شما نیاز به اضافه کردن restorelib.php دارید که مسئول restore کردن هر نمونه از ماژول و log آن است.

 

بیاین شروع کنیم :

برای شروع استفاده از یک بسته دانلود شده، لطفا ۷ مرحله گفته شده در NEWMODULE_Tutorial in How to Begin the Creation of a New Module paragraph را انجام دهید.
سپس، ساختار جداول خود را بر روی یک ورق ترسیم کنید، فایل db / install.xml را با توجه به پروژه خود ویرایش کنید،سپس ذخیره کنید، پوشه تغییر نام داده شده newmodule  خود را در moodle / mod قرار دهید و صفحه اعلان moodle را ببینید.

هرگز اضافه کردن کد به db / upgrade.php  را به صورت دستی انجام ندهید. ما همیشه از ویرایشگر  Site Administration block -> Miscellaneous -> XMLDB editor استفاده می کنیم و از آن می خواهم که کد را برای من بنویسد، که هر بار با قدرت و موفقیت این کار را انجام می دهد.

لطفا به یاد داشته باشید: در ماژول خود، هرگز از “پیام های جاسازی شده (embedded messages)” استفاده نکنید. مانند:

اما از get_string یا print_string استفاده کنید. به این ترتیب، ماژول شما چندین عمل را با تلاش بسیار کمی انجام خواهد داد. برای مثال:

در newmodule/lang/en_utf8/newmodule.php ذخیره می شود.

 

برخی از کدهای کوچک که به نظر ما مفید است:

بررسی قابلیت (capability) کاربر

 

تایپ کردن کد زیر در mod/newmodule/classes/newmodule.php :

تایپ کردن کد زیر در db/access.php :

جداول مورد استفاده را با استفاده از newmodule ویرایش کنید:

  • فایل db/install.xml را به صورت دستی بوسیله ویرایش فیلدها و یا جداول در ساختار xml ویرایش کنید.
  • به ویرایشگر  Site Administration block -> Miscellaneous -> XMLDB بروید و جداول ماژول جدیدتان را بارگزاری کنید.
  • از ویرایشگر XMLDB بخواهید که مفیدترین کدهایی که شما نیاز دارید را به فایل db/upgrade.php اضافه کند.
  • در خط

    xxxxxxxxxxxx را با ورژن newmodule خود جایگزین کنید.

  • ورژن مورد استفاده خود را تغییر دهید. (افزایش دهید)
  • صفحه اعلانات moodle را ببینید.

یک خط را به فرم logهای newmoduleتان اضافه کنید:

 

مطمئن شوید که کاربران راه دور با تایپ کردن URL به طور مستقیم در نوار آدرس قادر به تماس با صفحات و مشاهده آن ها نخواهند بود.

بعنوان مثال در ابتدای هر اسکریپ php :

 

پیشنهاداتی که به نظر ما مفید هستند:

برای اضافه کردن اسکریپت های php از کد زیر استفاده کنید :

برای اجرا کردن دوره ای تابع () newmodule_cron از کد زیر استفاده کنید:

تابع ()newmodule_cron شما به ازای xxxx ثانیه اجرا خواهد شد.

 

زمانی که به فایل config.php نیازی نیست، آن را وارد نکنید.

در اسکریپت های لایبرری نیازی نیست.

 

در داخل تابع های خود از متغیرهای عمومی $cm یا $newmodule استفاده نکنید اما بجای آن از پارامترهای مناسب و مخصوص تابع استفاده کنید.

بنابراین ، هرگز این گونه استفاده نکنید:

بلکه به این طریق استفاده کنید:

 

منبع : داکیومنت رسمی مودل

 

ساخت ماژول جدید در مودل

دیدگاهتان را بنویسید

نشانی ایمیل شما منتشر نخواهد شد. بخش‌های موردنیاز علامت‌گذاری شده‌اند *