در این پست تلاش میکنم به بهانه به روزرسانی افزونه ماهور کمی درباره افزونههای فایرفاکس و چگونگی ساخت یک افزونه برای فایرفاکس بنویسم.
در این پست تلاش میکنم به بهانه به روزرسانی افزونه ماهور کمی درباره افزونههای فایرفاکس و چگونگی ساخت یک افزونه برای فایرفاکس بنویسم.
افزونههای فایرفاکس
تا پیش از نوامبر ۲۰۱۷ ابزارهای مختلفی برای ساخت یک افزونه فایرفاکس وجود داشت اما در نسخههای به روزتر برخی از آنها مانند overlay add-ons، bootstrapped add-ons، Add-on SDK و … دیگر پشتیبانی نمیشوند. افزونههای جدید باید با استفاده از WebExtensions APIها ساخته شوند. اگر یک افزونه Legacy دارید برای سازگاری آن با نسخه های به روز فایرفاکس و ساخت WebExtension میتوانید از این راهنمای موزیلا استفاده کنید.
ساختار WebExtensionها
هر WebExtension یک فایل manifest.json دارد که ساختار، منابع و ویژگیهای آن را مشخص میکند. عکس زیر ساختار کلی فایل manifest.jason را در یک WebExtension نشان می دهد.
حداقل ورژن موتور ساخت محتوای مرورگر (gecko: content rendering engine)
شناسه افزونه برای موتور تولید محتوا (gecko.id)
اسکریپت پس زمینه (Background scripts): این اسکریپت در قالب یک صفحه ویژه به نام background page در پس زمینه اجرا میشود.
اسکریپتهای ساخت محتوا (Content scripts) که کار اصلی را بر عهده دارند و خوراک بخشهای گوناگون افزونه را تولید میکنند. افزونه ماهور به جای این کلید از experiment_apis بهره برده است. اسکریپت تولید محتوا درون API بارگذاری میشود.
رابط برنامهنویسی آزمایشی نرمافزار (experiment_apis): با این کلید میتوان یک رابط برنامه نویسی تازه برای استفاده در افزونه ساخت.
صفحههای پیش فرض که مانند یک صفحه وب معمولی میتوانند از فایلهای css و js استفاده کنند:
ساماندهی (options): ویژگیهای مربوط به آن در کلید options_ui تعریف میشود. این کلید در صفحه Add-ons Manager گزینه Preferences را برای افزونه نمایان میکند. با کلیک کردن روی آن، صفحه ساماندهی در این بخش بارگذاری شده و امکان تغییر ویژگیهای افزونه را فراهم میکند. (ست کردن ویژگی open_in_tab صفحه جدیدی برای بارگذاری باز خواهد کرد.)
صفحههای افزونه (Extension pages): هر افزونه میتواند جدا از صفحههای پیش فرض، دربردارنده صفحههای ویژه خودش نیز باشد که اینجا تعریف میشوند.
منابع مورد نیاز تولید محتوا (Web accessible resources): چنانچه بخواهیم از فایلهای HTML، CSS، JavaScript و … در تولید محتوای افزونه استفاده کنیم آنها را در اینجا مشخص میکنیم. (نمونه: چنانچه افزونه نیاز دارد که عکسهایی را در صفحههای وب نمایش دهد، آنها را در اینجا مسیردهی میکنیم تا به آنها دسترسی داشته باشیم.)
مجوزها (permissions): مجوزهای مورد نیاز برنامه با این کلید مشخص میشوند. برای مجوزهای اختیاری که نداشتن آنها جلوی اجرای برنامه را نمیگیرد از کلید optional_permissions استفاده میشود.
رابط برنامه نویسی افزونهها
برای درک بهتر APIهای موزیلا و چگونگی استفاده از آنها این راهنما را بخوانید.
در زیر نمونه یک API تعریف شده در فایل manifest.json را مشاهده میکنید.
در هر API یک یا چند فضای نام تعریف میشود، که اشیا آن را میتوان در اسکریپتهای افزونه فراخوانی کرد. برای هر API باید یک schema تعریف شود که ویژگیهای API را مشخص میکند. کلید schema در فایل manifest.json درون مسیر اصلی افزونه یک مسیر نسبی برای فایل schema مشخص میکند.
ویژگیهای اصلی پردازش سرپرست (parent process) و پردازشهای فرزند (child processes) با کلیدهای parent و child در script مسیردهی میشوند.
در حال حاضر تنها گزینههای مجاز کلید scops برای مشخص کردن محدوده دسترسی هر فضای نام addon-child و addon-parent هستند.
فایل schema برای افزونه ماهور:
در این فایل برای فضای نام MahourDate دو تابع addWindowListener و changeSettings تعریف شده است. تابع نخست در زمان شروع برنامه یک windowListener برای کنترل نمایش ستون تاریخ به برنامه اضافه میکند. تابع دوم با عوض کردن تنظیمات برنامه ستون تاریخ را دوباره میسازد و نمایش میدهد.
توجه: فراخوانی این توابع در background script باید با یک متغیر همراه باشد. بنابراین هر چند addWindowListener نیازی به ورودی ندارد، برای آن یک متغیر به نام hich (هیچ😂) تعریف شده است.
این توابع درون اسکریپت api/experiments.js تعریف شدهاند، که در ویژگی parent رابط برنامه نویسی MahourDate در فایل manifest.json افزونه مسیردهی شده است.
فایل experiment.js:
برای اینکه امکان فراخوانی توابع addWindowListener و changeSettings وجود داشته باشد، آنها را با الگوی مشخص شده در راهنمای موزیلا و درون getAPI(context) تعریف کردهایم.
تابع addWindowListener با eventهای onLoadWindow و onUnloadWindow به ترتیب توابع paint و unpaint را فراخوانی میکند. تابع paint با فراخوانی اسکریپت content/customcol.js محتوای ستون را تولید کرده و آن را نمایش میدهد. تابع unpaint نمایش ستون را متوقف و محتوای آن را پاک میکند.
مقدار پیش فرض متغیرهای قابل تنظیم برنامه در اینجا تعریف شدهاند. در صورت تغییر آنها در صفحه ساماندهی افزونه تابع changeSetting با واسطه background.js فراخوانی شده و ستون تاریخ را دوباره میسازد و نمایش میدهد.
فایل content/customcol.js:
محتوای اصلی ستون اینجا ساخته میشود و ستون جدید ایجاد میشود.
صفحه پس زمینه زمانی که افزونه مجوزهای لازم را داشته باشد، میتواند به WebExtension APIها دسترسی داشته باشد. همچنین با توجه به دسترسی به میزبان (host permissions) امکان فرستادن درخواستهای XHR را دارد. برای آگاهی بیشتر در این زمینه کلید واژه Cross-origin access را جستجو کنید.
اسکریپت پس زمینه دسترسی مستقیم به صفحههای وب ندارد، اما میتواند اسکریپتهای تولید محتوا (content scripts) را در آنها بارگذاری کند و با استفاده از message-passing API با آنها ارتباط برقرار کند. از این شیوه در افزونه ماهور استفاده شده است.
نکته: اسکریپتهای پس زمینه برای جلوگیری از دسترسی به کنشهای نابجا محدودیتهایی نیز دارند. نداشتن توان فراخوانی eval() نمونای از این محدودیتها است. برای آگاهی بیشتر Content Security Policy را بخوانید. همچنین امکان فراخوانی alert()، confirm()، یا prompt() نیز در این صفحه وجود ندارد.
کد اسکریپت پس زمینه ماهور:
برای استفاده از browser.storage.local.get() و browser.storage.local.set() در فایل manifest.jason مجوز storage گرفته شده است. MahourDate شناسه API تازه این افزونه است. با استفاده از browser.MahourDate.changeSettings(newSettings) یکی از توابع آن برای اعمال تنظیمات فراخوانی میشود.
به روز رسانی برای Thunderbird نسخه ۱۱۵ به بعد
در نسخه ۱۱۰ Thunderbird پشتیبانی از Custom Culomn متوقف شد و افزونه ماهور روی این نسخه از کار افتاد. با اضافه شدن API جدید در نسخه ۱۱۵ امکان به روز کردن کد و پشتیبانی از این نسخهها فراهم شد. اگر دوست دارید بیشتر بدونید اینجا دربارهاش گفتگو کردیم.
چون وقت کافی برای به روز کردن کدها نداشتم، کمی طول کشید، اما سرانجام ماهور نسخههای تازهتر تا ۱۲۸ را پشتیبانی میکند.
منابع مفید:
اگر با ساخت افزونهها آشنایی ندارید و تازه میخواهید شروع کنید این ویدیوی آقای شجاعی را ببینید:
برای تست افزونهها روی Thunderbird در صفحه Add-ons Manager روی Tools for all add-ons ( ) کلیک کنید. با انتخاب گزینه Debug Add-ons یک تب جدید باز میشود که در آن افزونه ها را میتوانید موقتا نصب و امتحان کنید. کافی است روی Load Temporary Add-on کلیک کنید و فایل manifest.json افزونه را انتخاب کنید.