مقالات مرتبط
آموزش موجود که در ادامه با هم شروع می کنیم در مورد جدیدترین مطلب منتشر شده در مودل است که ساخت ماژول جدید را آموزش می دهد. این آموزش طبق گفته داکیومنت رسمی مودل در حال پیشرفت است و ممکن است اصلاحات یا تغییراتی در آن به وجود بیاید ، و از کاربران مودل تقاضا شده است در صورت وجود انتقاد، پیشنهاد در مورد این مطلب به انجمن های بحث مرتبط با این موضوع در 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$ استفاده می کنید و برای سایر موارد از کد زیر استفاده می شود:
helpbutton(‘<<name of your help file saved in lang/xx_utf8/help/>>’, get_string(‘your_string’,’newmodule’), ‘newmodule’);
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 شما است. این بخش مربوط با گروه ها، نتایج، نمرات، دیدگاه ها و غیره است. این کد را می توان بوسیله تنظیم ارسال شیء به آن سفارشی کرد:
//——————————————————————————
// add standard elements, common to all modules
$features = new object();
$features->groups = false;
$features->groupings = false;
$features->groupmembersonly = true;
$this->standard_coursemodule_elements($features);
//——————————————————————————
نکات بیشتر در مورد این فایل:
- هنگامی که شما فرم ارسال شده توسط این فایل را ارسال می کنید، ماژول شما این تابع را اجرا می کند: newmodule_add_instance یا newmodule_update_instance .که هر دو از قبل در lib.php (در بالا توضیح داده شد) نوشته شده است.
- به نظر می رسد که چک باکس ها در فرم نمونه ویرایش کار نمی کنند.برای آزمایش آن، لطفا پارامتر newmodule$ را داخل تابع newmodule_update_instance با یک پرینت ساده از newmodule$ تایید کنید.
- شما متوجه خواهید شد که حتی با انتخاب یا عدم انتخاب چک باکس در نمونه فرم ویرایش newmodule، مقدار مربوطه در آرایه تغییری نخواهد کرد. این یک خطا نیست، اما حداقل ایراد کد است. شما متوجه خواهید شد که همه کارها با اضافه کردن یک کد ساده مثل این در ابتدای هر دو توابع خوب انجام خواهد شد:
$checkboxes = array(‘myfirstcheckboxfield’, ‘mysecondcheckboxfield’, and so fort with all your checkbox field);
foreach ($checkboxes as $checkbox) {
if (empty($newmodule->{$checkbox})) {
$newmodule->{$checkbox} = 0;
}
}
README.txt
فایلی است که در مورد آنچه که newmodule شما انجام می دهد، شامل دستورالعمل هایی برای شروع استفاده از افزونه ها و یا مانند مراحل نصب انها صحبت می کند. اگر قصد شما این باشد که ماژول خود را در Github منتشر کنید، شما باید فایل README.md را فراخوانی کنید و آن را به روش Markdown همگام سازی کنید.
thirdpartylibs.xml
لیستی از همه کتابخانه های ۳ قسمتی بهمراه یک افزونه.
بعنوان مثال:
<?xml version=”1.0″?>
<libraries>
<library>
<location>xx/yy</location>
<name>Library name</name>
<license>GPL</license>
<version>66.77</version>
<licenseversion>3.0+</licenseversion>
</library>
</libraries>
جایی که location یک مسیر نسبی به دایرکتوری یا فایل library است. لطفا توجه داشته باشید که license باید همیشه با GNU GPL 3 هماهنگ باشد.
version.php
فایل version.php فایل بسیار ساده و به همان اندازه بسیار مهم است.
برای درک این اهمیت، شما باید بدانید که دسته ای از اقدامات وجود دارد که مودل برای newmodule انجام می دهد اما تنها (تنها با یک استثنا) در زمان نصب newmodule. آنها جدول های ویرایش db و بارگزاری قابلیت ها هستند. اگر در طول زمان توسعه ماژول خود (که قبلا در محیط توسعه خود نصب کرده اید یا اینکه قبلا با کاربران راه دور به اشتراک گذاشته اید) نیاز به تغییر ساختار جداول newmodule خود پیدا کردید یا نیاز به تغییر قابلیت استفاده شده توسط newmodule خود داشتید، باید moodle را مجبور به ویرایش جداول و قابلیت بارگذاری مجدد کنید.
این کار به طریق زیر انجام می شود:
- اضافه کردن کد مناسب در newmodule / db / upgrade.php (برای انجام این کار از XMLDB استفاده کنید همانطور که در زیر همین صفحه بیان شده است)
- بالا بردن ورژن newmodule در فایل version.php
- دیدن صفحه نوتیفیکیشن از نصب 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)” استفاده نکنید. مانند:
echo ‘Welcome to this newmodule’;
اما از get_string یا print_string استفاده کنید. به این ترتیب، ماژول شما چندین عمل را با تلاش بسیار کمی انجام خواهد داد. برای مثال:
print_string(‘welcomemessage’,’newmodule’);
در newmodule/lang/en_utf8/newmodule.php ذخیره می شود.
$string[‘welcomemessage’] = ‘Welcome to this newmodule’;
برخی از کدهای کوچک که به نظر ما مفید است:
بررسی قابلیت (capability) کاربر
$mod = mod_newmodule\newmodule($cm)
if ($mod->usercandothis()) {
//user is allowed
} else {
// user is not allowed
}
تایپ کردن کد زیر در mod/newmodule/classes/newmodule.php :
namespace mod_newmodule;
class newmodule {
private $cm;
private $context;
__construct(\cm_info $cm) {
$this->cm = $cm;
$this->context = context_module::instance($cm->id);
}
public function usercandothis() {
return (has_capability(‘mod/newmodule:candothis’, $this->context));
}
}
تایپ کردن کد زیر در db/access.php :
$mod_newmodule_capabilities = array(
‘mod/newmodule:candothis’ => array(
‘captype’ => ‘read’,
‘contextlevel’ => CONTEXT_MODULE,
‘legacy’ => array(
‘teacher’ => CAP_ALLOW,
‘editingteacher’ => CAP_ALLOW,
‘admin’ => CAP_ALLOW
)
)
)
جداول مورد استفاده را با استفاده از newmodule ویرایش کنید:
- فایل db/install.xml را به صورت دستی بوسیله ویرایش فیلدها و یا جداول در ساختار xml ویرایش کنید.
- به ویرایشگر Site Administration block -> Miscellaneous -> XMLDB بروید و جداول ماژول جدیدتان را بارگزاری کنید.
- از ویرایشگر XMLDB بخواهید که مفیدترین کدهایی که شما نیاز دارید را به فایل db/upgrade.php اضافه کند.
- در خط
if ($result && $oldversion < xxxxxxxxxxxx)
xxxxxxxxxxxx را با ورژن newmodule خود جایگزین کنید.
- ورژن مورد استفاده خود را تغییر دهید. (افزایش دهید)
- صفحه اعلانات moodle را ببینید.
یک خط را به فرم logهای newmoduleتان اضافه کنید:
add_to_log($course->id, ‘newmodule’, ‘<<action already listed in log_display>>’, “view.php?id=$cm->id”, “$newmodule->id”);
مطمئن شوید که کاربران راه دور با تایپ کردن URL به طور مستقیم در نوار آدرس قادر به تماس با صفحات و مشاهده آن ها نخواهند بود.
بعنوان مثال در ابتدای هر اسکریپ php :
if (!defined(‘MOODLE_INTERNAL’)) {
die(‘Direct access to this script is forbidden.’); // It must be included from a Moodle page
}
پیشنهاداتی که به نظر ما مفید هستند:
برای اضافه کردن اسکریپت های php از کد زیر استفاده کنید :
require_once(‘myscript.php’);
برای اجرا کردن دوره ای تابع () newmodule_cron از کد زیر استفاده کنید:
$module->cron = xxxx;
providing some code in: function newmodule_cron()
تابع ()newmodule_cron شما به ازای xxxx ثانیه اجرا خواهد شد.
زمانی که به فایل config.php نیازی نیست، آن را وارد نکنید.
require_once(‘config.php’)
در اسکریپت های لایبرری نیازی نیست.
در داخل تابع های خود از متغیرهای عمومی $cm یا $newmodule استفاده نکنید اما بجای آن از پارامترهای مناسب و مخصوص تابع استفاده کنید.
بنابراین ، هرگز این گونه استفاده نکنید:
function newmodule_lookatthesky() {
global $cm, $newmodule;
// your stuff
}
بلکه به این طریق استفاده کنید:
function newmodule_lookatthesky($cm, $newmodule) {
// your stuff
}
منبع : داکیومنت رسمی مودل
