نصب و به روز رسانی

این بخش مروری بر نحوه نصب و به‌روزرسانی افزونه‌ها در جوملا ارائه می‌دهد.

نصب افزونه‌ها

• این بخش موارد زیر را پوشش می‌دهد:
• نحوه نصب افزونه‌ها - از طریق فایل مانیفست
• فرآیند کلی نصب، و نحوه نوشتن یک فایل اسکریپت برای تعامل با آن
• فایل ChangeLog
• بسته‌ها

فایل‌های مانیفست

شما افزونه‌های جوملا را از طریق یک فایل XML به نام مانیفست نصب می‌کنید، و نمونه‌های زیادی از جوملا وجود دارد که می‌توانید به عنوان پایه‌ای برای افزونه خود استفاده کنید:

- کامپوننت‌ها - در مسیر administrator/components

مثلاً administrator/components/com_contact/contact.xml 

- ماژول‌ها - در modules یا administrator/modules

مثلاً modules/mod_breadcrumbs/mod_breadcrumbs.xml 

- پلاگین‌ها - در plugins

مثلاً plugins/system/remember/remember.xml 

- قالب‌ها - در templates یا administrator/templates

مثلاً administrator/templates/atum/templateDetails.xml 

- زبان‌ها - در language یا administrator/language

مثلاً language/en-GB/install.xml 

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

قواعد نامگذاری فایل‌ها 

مهم است که فایل مانیفست خود را به درستی نام‌گذاری کنید. چرا که ممکن است علی رغم نصب افزونه اما فضای نام (namespace) افزونه به درستی ساخته نشده و در نتیجه آن افزونه اجرا نشود.

در اینجا قواعد نامگذاری برای انواع مختلف افزونه‌ها (طبق بخش ساخت افزونه‌ها) آمده است:

- کامپوننت‌ها: برای یک کامپوننت به نام com_example می‌توانید از com_example.xml یا example.xml استفاده کنید. 

- ماژول‌ها: برای یک ماژول به نام mod_example از mod_example.xml استفاده کنید. این نام باید با نام ماژول در بخش `<files>` مانیفست شما مطابقت داشته باشد: 

<files>
    <folder module="mod_example">services</folder>
    ...
</files>

یا اگر فعلاً فایلی مانند services/provider.php ندارید: 

<files>
    <filename module="mod_example">mod_example.php</filename>
    ...
</files>

 

- پلاگین‌ها: برای یک پلاگین plg_example از example.xml استفاده کنید. این نام باید با نام پلاگین در بخش `<files>` مانیفست شما مطابقت داشته باشد: 

<files>
    <folder plugin="example">services</folder>
    ...
</files>

 

یا اگر هنوز فایلی مانند services/provider.php ندارید: 

<files>
    <filename plugin="example">example.php</filename>
    ...
</files>

 

- قالب‌ها: فایل مانیفست شما باید templateDetails.xml نام داشته باشد. 

- زبان‌ها: از نام install.xml استفاده کنید. 

- فایل، کتابخانه، بسته: می‌توانید هر نامی بدهید، اما معمولاً کتابخانه‌ها lib_example.xml و بسته‌ها pkg_example.xml نامیده می‌شوند.

 برای کامپوننت‌ها، ماژول‌ها و پلاگین‌ها، فایل مانیفست باید با مقدار فیلد «element» در جدول #__extensions که رکورد افزونه را نگه می‌دارد، مطابقت داشته باشد (به جز اینکه در کامپوننت‌ها پیشوند "com_" ممکن است حذف شود). مقدار «element» نام داخلی افزونه در جوملا است.

ترتیب تعیین مقدار فیلد «element» در بانک اطلاعاتی به این صورت است:

1. از `<element>` در فایل مانیفست، یا 

2. از صفت "module=" یا "plugin=" در بخش `<files>`، یا 

3. از مقدار `<name>` (پس از پاک‌سازی متن).

عنصر ریشه (Root Element)

تگ اصلی فایل نصب به شکل زیر است:

<extension>
...
</extension>

 

این تگ شروع و پایان برای همه انواع افزونه‌ها یکسان است. درون این تگ، ویژگی‌های زیر مجاز هستند:

ویژگی (Attribute)	مقادیر (Values)	قابل اعمال برای (Applicable To)	توضیحات (Description)
type	component, file, language, library, module, package, plugin, template	همه افزونه‌ها	نوع افزونه (کامپوننت، ماژول، پلاگین و ...)
method	install, upgrade	همه افزونه‌ها	مقدار install (پیش‌فرض) به این معنی است که نصب‌گر در صورت وجود فایل یا پوشه افزونه قدیمی، با ملایمت متوقف می‌شود. مقدار upgrade اجازه می‌دهد نسخه جدید روی نسخه موجود نصب شود.
client	site, administrator	ماژول‌ها	مشخص می‌کند ماژول برای بخش کاربری (فرانت‌اند) است یا بخش مدیریت (بک‌اند).
group	رشته (string)	پلاگین‌ها	مشخص‌کننده گروه پلاگین است که معمولاً نام پوشه‌های داخل دایرکتوری /plugins می‌باشد. نصب‌گر برای گروه‌های جدید، پوشه جدیدی ایجاد می‌کند.

متادیتا (Metadata)

عناصر زیر می‌توانند برای وارد کردن متادیتا در فایل مانیفست استفاده شوند. اگرچه الزامی نیستند، اما بهتر است حداقل تگ‌های `name>`، `<author>`، `<version` و `<description>` را تعریف کنید که در فرم مدیریت افزونه‌های پیش‌فرض در بخش مدیریت استفاده می‌شوند:

 - `<name>` – نام افزونه (مثلاً com_banners). 

- `<author>` – نام نویسنده (مثلاً Joomla! Project). 

- `<creationDate>` – تاریخ ساخت یا عرضه (مثلاً April 2006). 

- `<copyright>` – بیانیه حق کپی‌رایت (مثلاً (C) 2020 - 2030 Open Source Matters. All rights reserved.). 

- `<license>` – نوع مجوز (مثلاً GNU General Public License version 3 or later؛ به فایل LICENSE.txt مراجعه شود). 

- `<authorEmail>` – ایمیل نویسنده (مثلاً این آدرس ایمیل توسط spambots حفاظت می شود. برای دیدن شما نیاز به جاوا اسکریپت دارید). 

- `<authorUrl>` – آدرس سایت نویسنده (مثلاً www.joomla.org). 

- `<version>` – شماره نسخه افزونه (مثلاً 1.6.0). 

- `<description>` – توضیح افزونه (ممکن است به عنوان راهنمای ابزار در صفحه مدیریت افزونه‌ها نمایش داده شود). 

- `<element>` – نام داخلی افزونه. اگر این مقدار حذف شود، از `<name>` پس از پاک‌سازی استفاده می‌شود.

فیلدهای `<name>` و `<description>` قابل ترجمه هستند. اگر از کلیدهای زبانی برای این دو استفاده می‌کنید، باید در فایل‌های زبان `.sys.ini` و `.ini` تعریف شده باشند.

فایل‌های فرانت‌اند (Frontend Files)

<files folder="from-folder">
    <filename>example.php</filename>
    <folder>examples</folder>
</files>

این بخش برای کپی کردن فایل‌ها از پوشه توسعه‌ی شما (from-folder) به دایرکتوری فرانت‌اند افزونه نصب شده استفاده می‌شود. می‌توانید فایل‌ها را به صورت جداگانه با `<filename>` مشخص کنید یا کل پوشه را با `<folder>` کپی کنید.

برای پلاگین‌ها و ماژول‌ها باید نقطه ورود کد خود را مشخص کنید. اگر در ماژول یا پلاگین خود از تزریق وابستگی (Dependency Injection) استفاده کرده‌اید و فایل services/provider.php دارید، به شکل زیر استفاده کنید:

<folder module="mod_example">services</folder>

 یا

<folder plugin="example">services</folder>

 

در اینجا "mod_example" یا "example" نام داخلی (یا همان 'element') ماژول یا پلاگین است.

اگر از فایل services/provider.php استفاده نمی‌کنید، باید به یک فایل مشخص اشاره کنید:

<filename module="mod_example">mod_example.php</filename>

یا

<filename plugin="example">example.php</filename>

 

فایل‌های رسانه‌ای (Media Files)

این دسته شامل موارد زیر است:

- فایل‌های جاوااسکریپت شما 

- فایل‌های CSS شما 

- هر تصویری که بخشی ذاتی از افزونه شما باشد (یعنی تصویرهایی که مدیر نباید بتواند آن‌ها را تغییر دهد).

(برای نمونه، تصاویر پرچم‌ها که در مسیر media/mod_languages/images/ قرار دارند و توسط سوییچر زبان استفاده می‌شوند.)

در محیط توسعه باید این فایل‌ها را در پوشه‌های جداگانه‌ی js/، css/ و images/ ذخیره کنید و سپس در فایل مانیفست از این ساختار استفاده کنید:

<media folder="media" destination="com_example">
    <folder>js</folder>
    <folder>css</folder>
    <folder>images</folder>
</media>

 نصب‌کننده این پوشه‌ها را به مسیرهای media/com_example/js، media/com_example/css و media/com_example/images منتقل می‌کند و در صورت نیاز پوشه com_example را می‌سازد.

این پوشه رسانه هم در بخش فرانت‌اند سایت و هم در بخش مدیریت استفاده می‌شود.

بخش مدیریت (Administration Section)

<administration>
    <!-- عناصر مختلف -->
</administration>

این بخش در عنصر `<administration>` تعریف می‌شود. فقط کامپوننت‌ها هم برای سایت و هم برای بخش مدیریت کاربرد دارند، بنابراین فقط فایل‌های مانیفست کامپوننت‌ها می‌توانند این عنصر را شامل شوند.

فایل‌های بخش مدیریت (Administrator Backend Files)

فایل‌هایی که باید در مسیر administrator کپی شوند، در داخل `<files>` زیر عنصر `<administration>` قرار می‌گیرند و می‌توانند شامل فایل‌های منفرد یا پوشه‌های کامل باشند، مشابه توضیحات بخش فایل‌های فرانت‌اند.

لینک‌ها و زیرمنوهای منوی مدیریت

این بخش برای تعریف لینک‌های منو و زیرمنوهای کامپوننت شما در منوی کناری مدیریت (زیر Components) است:

<administration>
    <menu>COM_EXAMPLE</menu>
    <submenu>
        <!-- دقت کنید همه & باید به &amp; تبدیل شوند تا فایل XML معتبر بماند و نصب‌کننده بتواند آن را پردازش کند -->
        <menu link="anoption=avalue&amp;anoption1=avalue1">COM_EXAMPLE_SUBMENU_ANOPTION</menu>
        <menu view="viewname">COM_EXAMPLE_SUBMENU_VIEWNAME</menu>
    </submenu>
</administration>

هر عنصر `<menu>` می‌تواند این ویژگی‌ها را داشته باشد:

ویژگی (Attribute)	توضیحات (Description)
link	لینکی که کاربر با کلیک روی منو به آن هدایت می‌شود. می‌توانید به جای آن از ویژگی view استفاده کنید.
view	پارامتری که به لینک اضافه می‌شود. مثال:

 

مثال: 

<menu view="cpanel">COM_EXAMPLE</menu>

ایجاد لینک `index.php?option=com_example&view=cpanel` خواهد کرد. می‌توانید به جای آن از `link` استفاده کنید. |

img: مسیر (نسبی) یک تصویر 16x16 پیکسل که کنار آیتم منو نمایش داده می‌شود. باید یک آدرس URL سازگار با فایل باشد (بدون فاصله و...)!

alt: متن جایگزین (alt) برای لینک.

 متن داخل تگ منو برچسب (label) منو است. اگر از رشته‌های زبانی برای اینها استفاده می‌کنید، باید در فایل `.sys.ini` کامپوننت تعریف شده باشند.

نصب‌کننده این موارد را در جدول#__menu پایگاه داده ذخیره می‌کند و جوملا از آنجا برای ساخت منوی مدیریت استفاده می‌کند. مثلاً منوهای مدیریت برای کامپوننت‌هایی مانند com_content در پوشه preset همان کامپوننت، تعریف شده‌اند مانند:

administrator/components/com_content/presets/content.xml

داشبوردها (Dashboards)

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

<dashboards>
    <dashboard title="Example Dashboard" icon="icon-lock">example</dashboard>
</dashboards>

 

پس از نصب افزونه، می‌توانید به داشبورد خود با آدرس زیر دسترسی داشته باشید:

administrator/index.php?option=com_cpanel&view=cpanel&dashboard=example

در بالای صفحه عنوان و آیکن نمایش داده می‌شود اما در ابتدا محتوا خالی خواهد بود. می‌توانید آیتم‌های داشبورد را با استفاده از پیش‌تنظیم‌ها (presets) و یا افزودن ماژول‌های بخش مدیریت در موقعیت cpanel-example تعریف کنید (مطابق توضیحات بخش داشبورد).

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

<administration>
    <menu>COM_EXAMPLE
        <params>
            <dashboard>example</dashboard>
        </params>
    </menu>
</administration>

 متن داخل تگ `<dashboard>` باید دقیقاً با متنی که داخل تگ `<dashboard>` در عنصر `<dashboards>` قرار دارد، مطابقت داشته باشد.

پیکربندی (Configuration)

برای ماژول‌ها، پلاگین‌ها و قالب‌ها می‌توانید پیکربندی را با استفاده از بخش `<config>` تعریف کنید. درون تگ‌های `<config>` فیلدهای تنظیمات را مطابق با توضیحات بخش فیلدهای فرم (Form Fields) مشخص می‌کنید.

نمونه‌های زیاد در افزونه‌های جوملا وجود دارد، مثلا ماژول mod_breadcrumbs.

پیکربندی از طریق بخش مدیریت، در صفحات مدیریت ماژول‌ها (Manage Modules)، مدیریت پلاگین‌ها (Manage Plugins) یا استایل‌های قالب (Template Styles) تعریف و ویرایش می‌شود.

برای کامپوننت‌ها نمی‌توانید از `<config>` استفاده کنید. جزئیات نحوه افزودن پیکربندی برای کامپوننت‌ها در بخش توسعه یک کامپوننت MVC/افزودن پیکربندی آمده است که با وجود اینکه برای جوملا ۳ نوشته شده، هنوز معتبر است. 

توجه: لینک بالا زمانی که آموزش کامپوننت MVC در مستندات اضافه شود به‌روزرسانی خواهد شد.

فضای نام (Namespace)

پیشوند فضای نام افزونه خود را به این صورت تعریف کنید:

<namespace path="src">Mycompany\Component\Example</namespace>

برای جزئیات بیشتر به مقالات مربوط به فضای نام‌ها در بخش مفاهیم کلی مراجعه کنید.

SQL

بخش SQL (عمدتاً برای کامپوننت‌ها استفاده می‌شود) به شما امکان می‌دهد تغییراتی در داده‌های بانک اطلاعاتی که متعلق به افزونه‌تان است، اعمال کنید.

سه نوع تغییر وجود دارد:

- Install: راه‌اندازی اولیه بانک اطلاعاتی برای نسخه اول افزونه، یا حداقل اولین نسخه‌ای که بانک اطلاعاتی را پیکربندی می‌کند. 

- Update: تغییرات بانک اطلاعاتی که هنگام ارتقا به این نسخه از نسخه قبلی اعمال می‌شود. 

- Uninstall: تغییرات بانک اطلاعاتی که هنگام حذف افزونه اعمال می‌شود.

برای هر نوع دیتابیس (مثلاً mysql) موارد زیر را دارید:

- یک فایل SQL برای نصب 

- یک فایل SQL برای حذف 

- یک پوشه شامل چند فایل SQL به‌روزرسانی که هر فایل به‌روزرسانی نسخه قبلی را به نسخه فعلی انجام می‌دهد

هر فایل SQL شامل مجموعه‌ای از دستورات SQL است که نام جدول‌ها با پیشوند `#__` نوشته شده‌اند، مثلاً `#__categories`.

به طور قراردادی، همه این فایل‌های SQL در پوشه‌ای به نام "sql" داخل پوشه administrator ذخیره می‌شوند. این پوشه باید در بخش فایل‌های administrator در فایل مانیفست شما تعریف شود، مثلاً:

<administration>
    <files folder="admin/">
        <folder>sql</folder>
    </files>
</administration>

 تعریف فایل نصب: 

<install>
    <sql>
        <file driver="mysql" charset="utf8">sql/example.install.sql</file>
    </sql>
</install>

 می‌توانید چندین تگ `<file>` برای درایورهای مختلف بانک اطلاعاتی داشته باشید.

تعریف فایل(های) حذف:

<uninstall>
    <sql>
        <file driver="mysql" charset="utf8">sql/example.uninstall.sql</file>
    </sql>
</uninstall>

تعریف فایل‌های به‌روزرسانی:

<update>
    <schemas>
        <schemapath type="mysql">sql/updates/mysql</schemapath>
    </schemas>
</update>

که به عنوان مثال پوشه `sql/updates/mysql` شامل چند فایل است، مانند:

- `0.0.2.sql` (برای ارتقا به نسخه ۰.۰.۲) 

- `0.0.۳.sql` (برای ارتقا از نسخه ۰.۰.۲ به ۰.۰.۳) 

- `0.0.۴.sql` (برای ارتقا از نسخه ۰.۰.۳ به ۰.۰.۴) و غیره

اگر اولین نسخه‌ای که نصب می‌کنید مثلا ۰.۰.۴ باشد، جوملا ابتدا فایل `example.install.sql` را اجرا کرده و سپس فایل‌های به‌روزرسانی را به ترتیب تا رسیدن به نسخه ۰.۰.۴ اعمال می‌کند.

اگر نسخه‌ای از افزونه را نصب کنید و برخی نسخه‌ها را رد کنید و بعد نسخه بعدی را نصب کنید، جوملا تمامی فایل‌های SQL به‌روزرسانی لازم را برای رسیدن از نسخه قبلی به نسخه جدید به ترتیب اجرا می کند.

نسخه نصب شده فعلی در جدول #__schemas نگهداری می‌شود. می‌توانید یک مثال عملی را در بخش توسعه یک کامپوننت MVC/استفاده از پایگاه داده پیدا کنید.

توجه: وقتی آموزش کامپوننت‌های MVC در راهنما قرار گرفت، لینک بالا را به‌روزرسانی کنید.

زبان‌ها

شما فایل‌های ini زبان خود را در ساختاری مانند این مشخص می‌کنید:

language

 ├─── en-GB

│     ├─── mod_hello.ini

│     └─── mod_hello.sys.ini

└─── fr-FR

       ├─── mod_hello.ini

       └─── mod_hello.sys.ini

نام زیرپوشه (مثلاً `en-GB`) باید با کد زبان مورد پشتیبانی افزونه شما مطابقت داشته باشد. فهرست کامل زبان‌های پشتیبانی‌شده توسط جوملا به همراه کد زبان‌ها را می‌توانید در [Joomla Language Downloads](https://downloads.joomla.org/language) مشاهده کنید.

به دلیل مسائل تاریخی، جوملا همچنین از نام فایل‌های زبان با پیشوند کد زبان پشتیبانی می‌کند، مثلاً `en-GB.mod_hello.ini`.

دو روش برای نصب فایل‌های زبان افزونه وجود دارد:

۱. استفاده از تگ `<languages>`

<languages folder="language">
    <language tag="en-GB">com_example.ini</language>
    <language tag="en-GB">com_example.sys.ini</language>
</languages>

 جوملا فایل‌های زبان را از پوشه تعیین‌شده در صفت `folder` کپی می‌کند به مسیرهای مناسب:

- در `/language` برای فرانت‌اند سایت (برای ماژول‌های سایت، قالب سایت و کامپوننت‌ها زمانی که `<languages>` مستقیماً داخل `<extension>` است) 

- در `/administrator/language` برای بک‌اند مدیریت (برای پلاگین‌ها، ماژول‌های مدیریت، قالب‌های مدیریت و کامپوننت‌ها زمانی که `<languages>` داخل `<administration>` باشد)

 در کد خود می‌توانید فایل زبان `.ini` را اینگونه بارگذاری کنید (مثال برای ماژول `mod_example`):

Factory::getApplication()->getLanguage()->load('mod_example');

 ۲. کپی مستقیم از پوشه زبان

<files>
    <folder>language</folder>
</files>

یا

<administration>
    <files>
        <folder>language</folder>
    </files>
</administration>

 

در این حالت پوشه `language` شما دقیقاً به محل هدف افزونه کپی می‌شود. بنابراین پوشه شما باید دقیقاً نام `language` داشته باشد، زیرا جوملا در این پوشه به دنبال فایل‌های زبان می‌گردد.

برای بارگذاری فایل زبان `.ini` در این روش باید مسیر پایه افزونه را هم بدهید (برای مثال برای ماژول سایت `mod_example`):

Factory::getApplication()->getLanguage()->load('mod_example', JPATH_BASE . '/modules/mod_example');

مزیت: در این حالت فایل‌های زبان به صورت نزدیک به افزونه شما باقی می‌مانند.

تفاوت دو روش در حذف و نصب مجدد زبان توسط مدیر سایت

اگر مدیر زبان را حذف کند:

- روش ۱: فایل‌های زبان افزونه هم حذف می‌شوند 

- روش ۲: فایل‌های زبان افزونه باقی می‌مانند

اگر مدیر بعداً زبان حذف‌شده را دوباره نصب کند:

- روش ۱: باید افزونه مجدداً نصب شود تا فایل‌های زبان بازیابی شوند 

- روش ۲: نیازی به اقدام اضافی نیست

فایل اسکریپت (Script File)

<scriptfile>script.php</scriptfile>

این تگ نام فایل اسکریپتی را مشخص می‌کند که شامل کد PHP اجراشونده در طول فرایند نصب است. توضیح کامل‌تر در بخش «روند نصب و فایل‌های اسکریپت» آمده است.

فایل‌های کتابخانه (Library Files)

مخصوص مانیفست‌هایی با نوع "library" است.

<libraryname>mylib</libraryname>

جوملا پوشه `libraries/mylib` را به عنوان مسیر مقصد در نظر می‌گیرد و فایل‌ها و پوشه‌ها را داخل آن کپی می‌کند.

اگر شرکت شما چند کتابخانه دارد و می‌خواهید آن‌ها را زیر پوشه `JPATH_SITE/libraries/mycompany` دسته‌بندی کنید، نام شرکت را به صورت زیر اضافه کنید:

<libraryname>mycompany/mylib1</libraryname>
<libraryname>mycompany/mylib2</libraryname>

کتابخانه‌ها در مسیرهای `libraries/mycompany/mylib1` و `libraries/mycompany/mylib2` نصب می‌شوند. حذف `mylib1` تاثیری روی `mylib2` ندارد.

سرور به‌روزرسانی (Update Server)

برای تعریف سرورهای آپدیت افزونه خود، از تگ `<updateservers>` و زیرتگ `<server>` به شکل زیر استفاده کنید:

<updateservers>
    <server type="extension" priority="1" name="Extension Update Site">http://example.com/extension.xml</server>
    <server type="collection" priority="2" name="Collection Update Site">http://example.com/collection.xml</server>
</updateservers>

 - `type`: نوع سرور به‌روزرسانی، مثلاً `extension` یا `collection`. 

- `priority`: اولویت برای انتخاب سرور (عدد کمتر اولویت بالاتری دارد). 

- `name`: نام نمایشی سرور آپدیت. 

- محتوای داخلی تگ آدرس فایل XML توصیف‌کننده اطلاعات به‌روزرسانی است.

برای اطلاعات بیشتر بخش «Update Servers» را مطالعه کنید.

یادداشت تغییرات (Changelog)

برای تعیین آدرس URL توضیحات تغییرات مربوط به این نسخه افزونه، از تگ زیر استفاده کنید:

<changelogurl>https://example.com/updates/changelog.xml</changelogurl>

 دقت کنید در مقدار تگ `<changelogurl>` نباید هیچ فاصله یا شکست خط (line break) قبل یا بعد از آدرس وجود داشته باشد.

برای اطلاعات بیشتر بخش «ChangeLogs» را ببینید.

کلیدهای دانلود (Download Keys)

کاربران می‌توانند کلیدهای دانلود خود را از طریق لیست «Update Sites» وارد و مدیریت کنند. زمانی که کاربر اقدام به به‌روزرسانی افزونه می‌کند، جوملا چک می‌کند که آیا کلید دانلود موجود است یا خیر. اگر کلید دانلود وجود داشته باشد، جوملا آن را به آدرس به‌روزرسانی اضافه می‌کند.

برای پشتیبانی از کلیدهای دانلود باید تگ `<dlid>` را در فایل مانیفست خود قرار دهید. این تگ دو آرگومان دارد:

- `prefix` (پیشوند) 

- `suffix` (پسوند)

ساختار تگ به شکل زیر است:

<dlid prefix="dlid=" suffix="&amp;dummy=my.zip"/>

 

- مقدار `prefix` قبل از کلید دانلود اضافه می‌شود. 

- مقدار `suffix` پس از کلید دانلود اضافه می‌شود.

مثلاً در مثال بالا، پارامتر کامل که به آدرس دانلود اضافه می‌شود این است:

dlid=KEY&amp;dummy=my.zip

نکته: کلید دانلود قبل از رخ دادن رویداد `onInstallerBeforePackageDownload` اضافه می‌شود، بنابراین این URL کامل به آن رویداد ارسال خواهد شد.

خلاصه و تطابق تگ‌ها با انواع افزونه‌ها (Summary)

این جدول ناتمام و نیاز به اعتبارسنجی دقیق دارد، اما نمایانگر پشتیبانی یا عدم پشتیبانی هر تگ XML در انواع افزونه‌های جوملا است:

تگ	Component	File	Language	Library	Module	Package	Plugin	Template
<sql>	بله	بله	خیر	خیر	بله	خیر	بله	بله
<languages>	بله	بله	خیر	بله	بله	بله	بله	بله
<tag>	خیر	خیر	بله	خیر	خیر	خیر	خیر	خیر
<media>	بله	خیر	بله	بله	بله	خیر	بله	بله
<config>	خیر	خیر	خیر	خیر	بله	خیر	بله	خیر
<script>	بله	بله	خیر	خیر	بله	بله	بله	بله
<updateserver>	بله	بله	بله	بله	بله	بله	بله	بله

فرآیند نصب و فایل‌های اسکریپت

در این بخش، مروری بر فرآیند نصب افزونه در جوملا و نحوه نوشتن فایل اسکریپت برای تعامل با آن ارائه شده است.

فایل اسکریپت نصب یک کلاس است که شامل ۵ تابع می‌باشد:

- preflight: در ابتدای فرآیند نصب فراخوانی می‌شود

- install، update، uninstall: در میانه فرآیند فراخوانی می‌شوند:

  - تابع install هنگام نصب اولیه افزونه اجرا می‌شود

  - تابع update هنگام به‌روزرسانی یک افزونه موجود اجرا می‌شود

  - تابع uninstall هنگام حذف یک افزونه اجرا می‌شود

- postflight: در پایان فرآیند نصب فراخوانی می‌شود

همچنین می‌توانید با نوشتن پلاگین‌های نصب که به رویدادهای مربوط به فرآیند گوش می‌دهند، با این فرآیند تعامل داشته باشید.

فرآیند نصب

روش‌های مختلفی برای نصب افزونه در جوملا وجود دارد و انواع مختلفی از افزونه‌ها، اما در نهایت فرآیند نصب برای همه نوع افزونه‌ها الگوی مشابهی دارد.

زمانی که قصد نصب افزونه دارید و فایل زیپ افزونه را انتخاب می‌کنید، فرآیند کلی به این صورت است: 

(اگر می‌خواهید این فرآیند را با دیباگر قدم به قدم اجرا کنید، بهتر است نقطه توقف (breakpoint) در مسیر `administrator/components/com_installer/src/Model/InstallModel.php::install` قرار دهید)

1. پلاگین‌های نوع "installer" بارگذاری می‌شوند و رویداد 'onInstallerBeforeInstallation' فعال می‌شود 

2. فایل زیپ در پوشه `/tmp` جوملا ذخیره و سپس در زیرپوشه‌ای از همان محل استخراج می‌شود 

3. رویداد 'onInstallerBeforeInstaller' فراخوانی می‌شود 

4. رویداد 'onExtensionBeforeInstall' فراخوانی می‌شود 

5. فایل زبان `.sys.ini` از فایل‌های نصب جدید یا در صورت فقدان از دایرکتوری افزونه موجود بارگذاری می‌شود 

6. اطلاعات پایه افزونه از فایل manifest خوانده می‌شود، مانند نوع افزونه 

7. اسکریپت نصب با `require_once` بارگذاری می‌شود 

8. تابع preflight فایل اسکریپت فراخوانی می‌شود 

9. فایل‌های افزونه از پوشه `/tmp` به محل نهایی در جوملا منتقل می‌شوند؛ مثلاً در نصب یک ماژول سایت mod_example، کد به `/modules/mod_example` کپی می‌شود 

10. رکورد افزونه در دیتابیس (در جدول `#__extensions`) ایجاد یا به‌روزرسانی می‌شود 

11. عملکردهای خاص نوع افزونه انجام می‌شود؛ مثلاً در نصب جدید ماژول‌ها، رکوردی در جدول `#__modules` ایجاد می‌شود 

12. تغییرات لازم در دیتابیس اعمال می‌شود 

13. توابع install / update / uninstall فایل اسکریپت فراخوانی می‌شوند 

14. مرتب‌سازی نهایی:

    - اگر رکوردی در جدول `#__updates` درباره نسخه جدید افزونه وجود داشته باشد، حذف می‌شود 

    - فایل manifest به دایرکتوری مقصد افزونه کپی می‌شود (برای کامپوننت‌ها، این دایرکتوری در `/administrator` خواهد بود) 

15. تابع postflight فایل اسکریپت فراخوانی می‌شود 

16. رویداد 'onExtensionAfterInstall' فعال می‌شود 

17. رویداد 'onInstallerAfterInstaller' فعال می‌شود 

18. پاک‌سازی‌های نهایی، مانند حذف فایل‌های موقت نصب انجام می‌شود 

نمونه فایل اسکریپت

ساده‌ترین روش نوشتن فایل اسکریپت، استفاده از تعریف رابط `\Joomla\CMS\Installer\InstallerScriptInterface` است که در مسیر `libraries/src/Installer/InstallerScriptInterface.php` قرار دارد. شما باید نمونه‌ای از کلاسی که این ۵ تابع نصب را پیاده‌سازی می‌کند، برگردانید.

شما می‌توانید:

- یک کلاس اسکریپت ناشناس که این رابط را پیاده‌سازی کرده باشد برگردانید، یا

- یک کلاس ارائه‌دهنده سرویس (service provider) ناشناس برگردانید که این کلاس اسکریپت را با کلید `InstallerScriptInterface::class` در کانتینر تزریق وابستگی (Dependency Injection Container) قرار می‌دهد. جوملا سپس این کلاس را از کانتینر دریافت می‌کند.

نمونه زیر از روش دوم استفاده می‌کند.

برای مشاهده نمونه‌ای از روش اول، به مرحله ۶ آموزش ماژول مراجعه کنید.

<?php

use Joomla\CMS\Application\AdministratorApplication;
use Joomla\CMS\Installer\InstallerAdapter;
use Joomla\CMS\Installer\InstallerScriptInterface;
use Joomla\CMS\Language\Text;
use Joomla\Database\DatabaseInterface;
use Joomla\DI\Container;
use Joomla\DI\ServiceProviderInterface;
use Joomla\Filesystem\File;
use Joomla\Filesystem\Exception\FilesystemException;

// phpcs:disable PSR1.Files.SideEffects
\defined('_JEXEC') or die;
// phpcs:enable PSR1.Files.SideEffects

return new class () implements ServiceProviderInterface {
  public function register(Container $container)
  {
    $container->set(
      InstallerScriptInterface::class,
      new class (
      $container->get(AdministratorApplication::class),
      $container->get(DatabaseInterface::class)
      ) implements InstallerScriptInterface {
        private AdministratorApplication $app;
        private DatabaseInterface $db;

        public function __construct(AdministratorApplication $app, DatabaseInterface $db)
        {
          $this->app = $app;
          $this->db  = $db;
        }

        public function install(InstallerAdapter $parent): bool
        {
          $this->app->enqueueMessage('Successful installed.');

          return true;
        }

        public function update(InstallerAdapter $parent): bool
        {
          $this->app->enqueueMessage('Successful updated.');

          return true;
        }

        public function uninstall(InstallerAdapter $parent): bool
        {
          $this->app->enqueueMessage('Successful uninstalled.');

          return true;
        }

        public function preflight(string $type, InstallerAdapter $parent): bool
        {
          return true;
        }

        public function postflight(string $type, InstallerAdapter $parent): bool
        {
          $this->deleteUnexistingFiles();

          return true;
        }

        private function deleteUnexistingFiles()
        {
          $files = [];  // overwrite this line with your files to delete

          if (empty($files)) {
            return;
          }

          foreach ($files as $file) {
            try {
              File::delete(JPATH_ROOT . $file);
            } catch (\FilesystemException $e) {
              echo Text::sprintf('FILES_JOOMLA_ERROR_FILE_FOLDER', $file) . '<br>';
            }
          }
        }
      }
    );
  }
};

 

این کد PHP یک نمونه‌ی کامل از یک کلاس سرویس‌دهنده جوملاست که رابط `InstallerScriptInterface` را پیاده‌سازی می‌کند و به فرآیند نصب، آپدیت و حذف افزونه واکنش نشان می‌دهد

توضیح کد:

- ابتدا از فضای نام‌های مورد نیاز جوملا وارد شده‌اند (مثلاً `AdministratorApplication`، `InstallerAdapter`، `InstallerScriptInterface` و غیره).

- متد `register` در این کلاس، شی اسکریپت نصب را در کانتینر وابستگی ثبت می‌کند.

- اسکریپت نصب خودش یک کلاس است که `InstallerScriptInterface` را پیاده‌سازی کرده و متدهای زیر را دارد:

  - install: هنگام نصب اولیه افزونه اجرا شده و پیام «نصب موفقیت‌آمیز بود» را نمایش می‌دهد.

  - update: هنگام بروزرسانی اجرا شده و پیام «بروزرسانی موفقیت‌آمیز بود» را نمایش می‌دهد.

  - uninstall: هنگام حذف افزونه اجرا شده و پیام «حذف موفقیت‌آمیز بود» را نمایش می‌دهد.

  - preflight: قبل از شروع فرآیند (نصب، بروزرسانی، حذف) اجرا می‌شود و فقط `true` برمی‌گرداند.

  - postflight: پس از اتمام فرآیند اجرا می‌شود، در اینجا تابع `deleteUnexistingFiles` فراخوانی می‌شود که فایل‌هایی که دیگر وجود ندارند را حذف کند.

- تابع `deleteUnexistingFiles`: اینجا قرار است شما لیستی از فایل‌ها که باید حذف شوند را جایگزین متغیر `$files` کنید. سپس در حلقه تلاش می‌کند آن‌ها را حذف کند و در صورت بروز خطا، پیام خطا را نمایش می‌دهد.

تغییرات (Changelogs)

توسعه‌دهندگان افزونه می‌توانند از قابلیت جوملا برای خواندن فایل changelog و نمایش گرافیکی تغییرات استفاده کنند. اگر نسخه‌ای مشخص در فایل changelog یافت نشود، دکمه نمایش changelog نمایش داده نخواهد شد.

نحوه نمایش تغییرات در یک نسخه:

نمایش changelog

فایل‌های changelog می‌توانند در دو بخش از پنل مدیریت جوملا نمایش داده شوند:

1. مدیریت افزونه‌ها (Manage Extensions)

- شما می‌توانید روی شماره نسخه کلیک کنید تا changelog آن نمایش داده شود.

- برای فعال کردن این قابلیت باید در فایل manifest نصب افزونه مشخص کنید جوملا باید از کجا جزئیات changelog را بخواند، برای مثال:

<changelogurl>https://example.com/updates/changelog.xml</changelogurl>

لطفا توجه کنید: آدرس داخل تگ `<changelogurl>` نباید شامل فاصله یا شکست خط قبل یا بعد از آن باشد.

2. به‌روزرسانی افزونه‌ها (Update Extensions)

- برای فعال کردن این بخش هم باید در فایل سرور به‌روزرسانی افزونه (`update server file`) مشخص کنید که جوملا از کجا changelog را بخواند، به صورت مشابه:

<changelogurl>https://example.com/updates/changelog.xml</changelogurl>

 این ویژگی در حال حاضر کار نمی‌کند؛ برای اطلاعات بیشتر به [مسئله شماره 43505 در سایت جوملا] مراجعه کنید.

https://issues.joomla.org/tracker/joomla-cms/43505

فایل Changelog

نمونه‌ای از فایل changelog به صورت زیر است:

<changelogs>
    <changelog>
        <element>com_lists</element>
        <type>component</type>
        <version>4.0.0</version>
        <security>
            <item>Item A</item>
            <item>Item b</item>
        </security>
        <fix>
            <item>Item A</item>
            <item>Item b</item>
        </fix>
        <language>
            <item>Item A</item>
            <item>Item b</item>
        </language>
        <addition>
            <item>Item A</item>
            <item>Item b</item>
        </addition>
        <change>
            <item>Item A</item>
            <item>Item b</item>
        </change>
        <remove>
            <item>Item A</item>
            <item>Item b</item>
        </remove>
        <note>
            <item>Item A</item>
            <item>Item b</item>
        </note>
    </changelog>
    <changelog>
        <element>com_lists</element>
        <type>component</type>
        <version>0.0.2</version>
        <security>
            <item>Big issue</item>
        </security>
    </changelog>
</changelogs>

 نکات مهم درباره فایل changelog:

- می‌توانید چندین عنصر `<changelog>` درون عنصر اصلی `<changelogs>` داشته باشید، یکی برای هر نسخه افزونه.

- هر عنصر `<changelog>` باید سه گره (node) اصلی زیر را داشته باشد:

  - `<element>`: نام افزونه (مثلاً `com_lists`)

  - `<type>`: نوع افزونه (مانند `component`، `module`، و غیره)

  - `<version>`: شماره نسخه مربوط به آن changelog

این اطلاعات برای شناسایی changelog درست برای افزونه به کار می‌روند.

نوع تغییرات پشتیبانی شده:

در هر changelog می‌توانید انواع مختلف تغییرات را مشخص کنید. این انواع عبارتند از:

- security: مشکلات امنیتی رفع شده 

- fix: باگ‌های رفع شده 

- language: تغییرات در زبان 

- addition: قابلیت‌های جدید اضافه شده 

- change: تغییرات کلی 

- remove: قابلیت‌های حذف شده 

- note: اطلاعات اضافی برای کاربر 

می‌توانید هر یک از این گره‌ها را به تعداد لازم تکرار کنید و هر کدام شامل یک یا چند `<item>` باشد.

قالب‌بندی متن

متن داخل آیتم‌ها می‌تواند ساده (plain text) یا HTML باشد؛ اما در صورت استفاده از HTML باید داخل تگ‌های `<![CDATA[ ... ]]>` قرار گیرد تا مشکلی در خواندن فایل پیش نیاید، مثل:

<security>
    <item><![CDATA[<h2>You MUST replace this file</h2>]]></item>
</security>

 

بسته‌ها (Packages)

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

ساختن یک بسته

یک افزونه بسته (package) با فشرده‌سازی تمامی فایل‌های ZIP مربوط به افزونه‌های جداگانه، همراه با یک فایل manifest XML بسته ساخته می‌شود. برای مثال، اگر بسته شما شامل موارد زیر باشد:

- کامپوننت helloworld 

- ماژول helloworld 

- کتابخانه helloworld 

- پلاگین سیستمی helloworld 

- قالب helloworld 

ساختار پوشه `pkg_helloworld` به شکل زیر خواهد بود: 

نمونه فایل manifest برای بسته: pkg_helloworld.xml

<?xml version="1.0" encoding="UTF-8" ?>
<extension type="package" version="1.6" method="upgrade">
    <name>Hello World Package</name>
    <author>Hello World Package Team</author>
    <creationDate>today</creationDate>
    <packagename>helloworld</packagename>
    <version>1.0.0</version>
    <url>http://www.yoururl.com/</url>
    <packager>Hello World Package Team</packager>
    <packagerurl>http://www.yoururl.com/packagerurl</packagerurl>
    <description>Example package to combine multiple extensions</description>
    <update>http://www.updateurl.com/update</update>
    <scriptfile>pkg_script.php</scriptfile>
    <blockChildUninstall>true</blockChildUninstall>
    <files folder="constituents">
        <file type="component" id="com_helloworld">com_helloworld.zip</file>
        <file type="module" id="helloworld" client="site">mod_helloworld.zip</file>
        <file type="library" id="helloworld">lib_helloworld.zip</file>
        <file type="plugin" id="helloworld" group="system">plg_sys_helloworld.zip</file>
        <file type="template" id="helloworld" client="site">tpl_helloworld.zip</file>
    </files>
</extension>

نکات مهم در فایل manifest بسته:

- `type="package"` مشخص می‌کند این افزونه یک بسته است.

- `method="upgrade"` بیانگر نحوه به‌روزرسانی بسته است.

- در بخش `<files>`، هر فایل zip افزونه فرزند به همراه نوع و شناسه (id) و در صورت لزوم اطلاعات اضافی مثل `client` (برای سایت یا مدیریت) یا `group` (برای پلاگین‌ها) مشخص شده است.

- تگ `<scriptfile>` می‌تواند اسکریپت نصب اختصاصی بسته را معرفی کند.

- `blockChildUninstall` وقتی true باشد، از حذف جداگانه افزونه‌های درون بسته توسط کاربر جلوگیری می‌کند.

پس از اینکه پوشه `pkg_helloworld` را زیپ کردید، بسته افزونه را مانند سایر افزونه‌ها به صورت عادی نصب می‌کنید. پس از نصب، در بخش مدیریت افزونه‌ها (Manage Extensions) خواهید دید:

- یک ورودی کلی برای بسته `helloworld` 

- ورودی‌هایی جداگانه برای هر یک از افزونه‌های تشکیل‌دهنده‌ی بسته

این ورودی‌ها متناظر با ردیف‌های جدول `#__extensions` در دیتابیس جوملا هستند.

نکات مهم برای اطمینان از عملکرد صحیح نصب/حذف بسته:

نام‌گذاری فایل manifest

- فایل manifest بسته باید دقیقا به صورت `pkg_<packagename>.xml` نامگذاری شود، که `<packagename>` همان مقدار موجود در تگ `<packagename>` در فایل XML است. 

- در مثال بالا، چون `<packagename>helloworld</packagename>` است، بنابراین نام فایل باید `pkg_helloworld.xml` باشد. 

- هنگام حذف بسته، جوملا به دنبال همین فایل manifest می‌گردد؛ اگر نام فایل صحیح نباشد، حذف با خطا مواجه شده و اعلام می‌کند که فایل manifest یافت نشده است.

مقدار صفت `id` در تگ `<file>`

- مقدار `id` در هر عنصر `<file>` مربوط به افزونه‌های تشکیل‌دهنده باید دقیقا برابر با ستون `element` در جدول `#__extensions` برای آن افزونه باشد. 

- این مقدار معمولا همان نام یکتای افزونه است (مثلاً `com_helloworld` برای کامپوننت، `helloworld` برای ماژول، پلاگین و غیره). 

- جوملا هنگام حذف بسته با استفاده از این مقدار، رکورد افزونه را در دیتابیس پیدا و حذف می‌کند. اگر این مقدار اشتباه باشد، حذف افزونه فرزند انجام نمی‌گیرد.

صفت `group` در پلاگین‌ها

- برای پلاگین‌ها، مقدار صفت `group` باید مشخص شود تا نصب‌کننده بسته بتواند پلاگین را به درستی پیدا کرده و هنگام حذف آن را شناسایی کند. 

- این مقدار باید مطابق با صفت `group` تعریف شده در داخل تگ `<extension>` در فایل manifest پلاگین باشد و همچنین نام زیرپوشه مربوطه در مسیر `/plugins` جوملا است. 

- برای مثال، `group="system"` به پوشه `/plugins/system` اشاره دارد.

تگ `<blockChildUninstall>`

- این تگ وقتی مقدار `true` دارد، مانع حذف جداگانه افزونه‌های فرزند توسط مدیر سایت می‌شود. 

- اگر این تگ را حذف کنید یا مقدار آن `false` باشد، مدیر می‌تواند یکی از افزونه‌های تشکیل‌دهنده را به صورت مستقل حذف کند و دیگر افزونه‌ها بدون تغییر باقی بمانند.

سایر تگ‌ها

- بقیه تگ‌های فایل manifest بسته همچون سایر افزونه‌ها کار می‌کنند و مطابق آنچه در مستندات مربوط به فایل manifest و اسکریپت‌های نصب گفته شده است، قابل استفاده‌اند.

معرفی سامانه‌های به‌روزرسانی (Update Servers) در جوملا

جوملا برای به‌روزرسانی افزونه‌ها، مفهومی به نام سرور به‌روزرسانی (Update Server) دارد که فرآیند آپدیت افزونه‌ها را در دو مرحله انجام می‌دهد:

1. پیدا کردن آپدیت‌های موجود برای افزونه‌های نصب شده

2. انتخاب آپدیت و نصب آن

معمولاً مدیر سایت از طریق صفحه مدیریت سیستم در بخش **Update / Extensions** این کار را انجام می‌دهد:

- روی دکمه «Check For Updates» کلیک کرده تا وجود آپدیت‌های جدید بررسی شود

- سپس آپدیت‌های مورد نظر را علامت زده و با کلیک روی «Update»، آن‌ها را نصب می‌کند

به‌علاوه، جوملا هنگام ورود مدیر به بخش مدیریت به‌صورت خودکار نیز آپدیت‌ها را بررسی می‌کند.

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

هر افزونه‌ای که از طریق سرور به‌روزرسانی بروزرسانی می‌شود، یک URL دارد که آدرس یک فایل XML را مشخص می‌کند. این فایل XML حاوی اطلاعات آپدیت‌های موجود برای آن افزونه است (و معمولاً روی سرور توسعه‌دهنده افزونه قرار می‌گیرد).

شما می‌توانید آدرس این URLها را در بخش سیستم مدیریت، قسمت **Update / Update Sites** مشاهده کنید و با کلیک روی آن‌ها محتوای فایل XML را ببینید.

محتوای فایل XML به‌روزرسانی

این فایل حاوی اطلاعاتی است که شامل موارد زیر می‌شود:

- نام افزونه

- نسخه آپدیت موجود

- آدرس فایل zip حاوی نسخه جدید افزونه

- محدودیت‌های مربوط به ورژن جوملا، نسخه PHP و سایر موارد

- سایر جزئیات مورد نیاز برای شناسایی و اعتبارسنجی آپدیت

مثال پایه یک فایل update.xml:

<updates>
<update>
<name>Example component</name>
<description>Example component</description>
<element>com_example</element>
<type>component</type>
<version>1.0.0</version>
<client>administrator</client>
<downloads>
<downloadurl type="full" format="zip">http://example.com/com_example-1-0-0.zip</downloadurl>
</downloads>
<targetplatform name="joomla" version="((4\.4)|(5\.(0|1|2|3|4|5|6|7|8|9)))" />
<php_minimum>8.1</php_minimum>
</update>
</updates>

 

در این مثال:

- افزونه دارای نام و نسخه مشخص است 

- آدرس فایل zip آپدیت تعیین شده (`downloadurl`) 

- محدودیت‌هایی برای نسخه جوملا (مثلاً نسخه ۴.۴ یا ۵.x) 

- محدودیت حداقل نسخه PHP (مثلاً ۸.۱)

روند کاری هنگام بررسی آپدیت توسط جوملا

- جوملا فایل XML هر سرور به‌روزرسانی را با درخواست HTTP دریافت می‌کند 

- صحت ساختار XML بررسی می‌شود 

- نسخه افزونه جدید با نسخه نصب‌شده مقایسه می‌شود 

- محدودیت‌ها (نسخه جوملا، نسخه PHP و ...) بررسی می‌شود 

- اگر آپدیت برای سایت معتبر باشد، رکوردی از آن در جدول `#__updates` ذخیره می‌شود 

- فقط جدیدترین نسخه معتبر ذخیره می‌شود (اگر چند نسخه معتبر باشند)

سه قدم برای راه‌اندازی یک سرور به‌روزرسانی

 1. ایجاد فایل XML به‌روزرسانی

   فایل XML با قالب بالا را ساخته و روی سرور خود قرار دهید. این فایل باید شامل اطلاعات کامل برای هر ورژن جدید باشد.

2. ذخیره فایل zip آپدیت

فایل زیپ نسخه جدید افزونه باید روی همان سرور و در همان آدرسی قرار گیرد که در `<downloadurl>` تعیین شده است.

3. اعلام به جوملا آدرس سرور به‌روزرسانی

   در فایل manifest افزونه خود، تگ `<updateservers>` را اضافه کنید برای مثال:

<updateservers>
<server type="extension" name="Example Updates">http://example.com/extension.xml</server>
</updateservers>

 

شما می‌توانید در تگ `<updateservers>` چندین سرور به‌روزرسانی تعریف کنید. اگر بیش از یک سرور داشته باشید، می‌توانید با استفاده از صفت `priority` ترتیب بررسی این سرورها را کنترل کنید.

انواع سرورهای به‌روزرسانی

- type="extension": سرور به‌روزرسانی مخصوص یک افزونه خاص 

- type="collection": سرور به‌روزرسانی جمع‌آوری شده که ممکن است به‌روزرسانی چند افزونه یا بسته را پوشش دهد

نمونه تعریف چند سرور به‌روزرسانی در فایل manifest

<updateservers>
    <server type="collection">https://example.com/list.xml</server>
    <server type="extension" priority="2" name="My Extension's Updates">http://example.com/extension.xml</server>
</updateservers>

- در این مثال، ابتدا سرور نوع `collection` بررسی می‌شود 

- سرور با `type="extension"` دارای اولویت ۲ است و پس از سرور اول بررسی می‌شود

نکته مهم درباره مقدار `name`

- برای مقدار ویژگی `name` بهتر است رشته‌های متنی عادی (plain text) به کار ببرید، نه کلیدهای زبان (language strings)، زیرا جوملا گاهی اوقات این مقادیر را ترجمه نمی‌کند.

روند نصب به‌روزرسانی‌ها در جوملا

وقتی یک به‌روزرسانی در جدول `#__updates` ثبت می‌شود، مدیر سایت آن را در بخش Update / Extensions در پیشخوان مدیریت مشاهده می‌کند. در صورت انتخاب افزونه و کلیک روی «Update»، جوملا به ترتیب عملیات زیر را انجام می‌دهد:

1. دوباره یک درخواست HTTP به آدرس فایل XML به‌روزرسانی ارسال می‌کند. 

2. فایل XML را پردازش می‌کند و بررسی می‌کند که شرایط نصب نسخه جدید هنوز برقرار باشد (مثلاً محدودیت نسخه جوملا یا PHP تغییر نکرده باشد). 

3. درخواست HTTP به آدرس فایل ZIP به‌روزرسانی ارسال می‌کند و فایل دریافت‌شده را در پوشه `/tmp` ذخیره می‌کند. 

4. از طریق فایل ZIP دانلود شده، نسخه جدید افزونه را نصب می‌کند.

نوع سرور Collection (مجموعه‌ای)

نوع سرور collection به شما امکان مدیریت مجموعه‌ای از فایل‌های XML به‌روزرسانی را می‌دهد. کاربردهای رایج آن عبارتند از:

- زمانی که افزونه شما یک بسته (package) است و می‌خواهید کاربران بتوانند کامپوننت‌های درون بسته را به صورت جداگانه به‌روزرسانی کنند. 

- داشتن چند فایل XML مختلف برای نسخه‌های مختلف جوملا.

 مثال از فایل XML سرور به‌روزرسانی collection

جوملا پک زبان (Language Pack) از این نوع استفاده می‌کند. مثلاً:

<extensionset name="Accredited Joomla! Translations" description="Accredited Joomla! Translations Updates">
    <extension name="Afrikaans" element="pkg_af-ZA" type="package" version="4.4.2.2" detailsurl="https://update.joomla.org/language/details4/af-ZA_details.xml" />
    <extension name="Arabic Unitag" element="pkg_ar-AA" type="package" version="4.0.2.1" detailsurl="https://update.joomla.org/language/details4/ar-AA_details.xml" />
    ...
</extensionset>

- کل فایل باید داخل تگ `<extensionset>` قرار گیرد. 

- تگ `<extensionset>` می‌تواند دو پارامتر اختیاری `name` و `description` داشته باشد. 

- هر افزونه در مجموعه با یک تگ `<extension>` تعریف می‌شود که باید تمام پارامترهای زیر را داشته باشد:

نوع سرور Extension

نوع سرور extension مختص هر افزونه به صورت جداگانه است و ارائه‌کننده اطلاعات به‌روزرسانی آن افزونه می‌باشد.

- در نهایت هر سرور به‌روزرسانی نوع collection به یک یا چند سرور نوع extension اشاره می‌کند. 

- سرورهای extension فایل‌های XML دارند که به صورت دقیق‌تر آخرین نسخه‌ها و لینک‌های دانلود را معرفی می‌کنند.

در اینجا یک نمونه از نوع سرور افزونه - برای نسخه جوملا ۴.۴ - آورده شده است:

فایل https://update.joomla.org/core/j4/default.xml

<updates>
    <update>
        <name>Joomla! 4.4</name>
        <description>Joomla! 4.4 CMS</description>
        <element>joomla</element>
        <type>file</type>
        <version>4.4.4</version>
        <infourl title="Joomla 4.4.4 Release">
            https://www.joomla.org/announcements/release-news/5907-joomla-5-1-0-and-joomla-4-4-4-are-here.html
        </infourl>
        <downloads>
        <downloadurl type="full" format="zip">
            https://downloads.joomla.org/cms/joomla4/4-4-4/Joomla_4.4.4-Stable-Update_Package.zip
        </downloadurl>
        <downloadsource type="full" format="zip">
            https://github.com/joomla/joomla-cms/releases/download/4.4.4/Joomla_4.4.4-Stable-Update_Package.zip
        </downloadsource>
        <downloadsource type="full" format="zip">
            https://update.joomla.org/releases/4.4.4/Joomla_4.4.4-Stable-Update_Package.zip
        </downloadsource>
        </downloads>
        <tags>
            <tag>stable</tag>
        </tags>
        <supported_databases mysql="5.6" mariadb="10.1" postgresql="11.0"/>
        <php_minimum>7.2.5</php_minimum>
        <sha256>
            02158d2d9e388aa21718fcfc98ea6c0c0c306f130ce6b3ecd02ade7ced863e61
        </sha256>
        <sha384>
            0ecae1ebae84584433c7d60f7bd2bedb4bc55c73f89e9fc0416d9445dab6670a6b29bb3aef84e80177f28a0b9cac06eb
        </sha384>
        <sha512>            f774f13e97d6d96ffe1fb5847088120734bbe14b3e49c6e9042e725c3b21a8960f89f034bd517157aa7bcb588a11271dc4dc646010530e08a9c90eeb82dfa377
        </sha512>
        <maintainer>Joomla! Production Department</maintainer>
        <maintainerurl>https://www.joomla.org</maintainerurl>
        <section>STS</section>
        <targetplatform name="joomla" version="4.[1234]"/>
    </update>
</updates>

در فایل XML انتخابی برای سرور به‌روزرسانی از نوع extension، می‌توانید چندین تگ <update> داشته باشید که همه باید داخل یک تگ والد <updates> قرار گیرند. هر تگ <update> بیانگر یک نسخه از افزونه شماست که منتشر شده است.

نکات مهم درباره تگ‌های <update> در فایل XML:

• برای هر نسخه جدیدی که از افزونه منتشر می‌کنید باید یک تگ <update> مجزا تعریف کنید.
• این به جوملا اجازه می‌دهد که نسخه‌های مختلف را ردیابی و مدیریت کند.
• ممکن است چندین به‌روزرسانی برای یک نسخه خاص افزونه وجود داشته باشد که هر کدام مربوط به نسخه‌های متفاوت جوملا هستند؛

بنابراین، برای هر ترکیب نسخه افزونه و نسخه جوملای هدف، یک <update> جداگانه ایجاد می‌شود.

در ادامه توضیح مختصری از عناصر کلیدی یک بخش `<update>` در فایل XML به‌روزرسانی جوملا آورده شده است:

- name (الزامی) 

  نام افزونه که در ستون «Name» صفحه مدیریت افزونه‌ها نمایش داده می‌شود.

- description (اختیاری) 

  توضیح کوتاهی درباره افزونه. اگر از <![CDATA[]]> استفاده می‌کنید، دقت کنید که استفاده از نقل قول دوتایی (`"`) باعث ایجاد مشکل می‌شود، بهتر است از نقل قول تکی (`'`) استفاده کنید.

- element (الزامی) 

  نام یکتای افزونه نصب شده که باید مطابق مقدار `plugin` در فایل manifest پلاگین باشد. برای مثال اگر در manifest پلاگین دارید `<filename plugin="pluginname">pluginname.php</filename>` مقدار این تگ می‌شود `pluginname`.

- type (الزامی) 

  نوع افزونه مانند component، module، plugin و غیره.

- folder (الزامی برای پلاگین‌ها) 

  تنها برای پلاگین‌ها، نوع پلاگین مانند system، content و غیره.

- client (الزامی برای ماژول‌ها و قالب‌ها) 

  مشخص می‌کند افزونه برای «frontend» یا «backend» است. مقادیر ممکن: `site` یا `administrator`. 

  هشدار: پلاگین‌ها و ماژول‌های سمت کاربر به طور خودکار با client = `site` نصب می‌شوند ولی اگر در به‌روزرسانی مقدار client داده نشود، به طور پیش‌فرض `administrator` در نظر گرفته شده و آپدیت نمایش داده نمی‌شود چون با هیچ افزونه‌ای مطابقت نخواهد داشت.

- version (الزامی) 

  نسخه جدید افزونه.

- infourl (اختیاری) 

  آدرس صفحه‌ای برای نمایش اطلاعات بیشتر درباره به‌روزرسانی.

- downloads (الزامی) 

  بخش حاوی آدرس‌های دانلود فایل‌های به‌روزرسانی.

  - downloadurl (الزامی) 

    آدرس دانلود اصلی، که باید دو ویژگی زیر داشته باشد: 

    - `type`: نوع بسته (مثلاً full یا upgrade) 

    - `format`: فرمت بسته (مثلاً zip یا tar)

  - downloadsource (اختیاری) 

آدرس جایگزین دانلود (اگر دسترسی به `downloadurl` اصلی میسر نبود). می‌توانید چندین بار استفاده کنید. همچنین باید ویژگی‌های `type` و `format` مشابه `downloadurl` داشته باشد. 

توجه: آدرس URL باید در یک خط بدون خط‌نوشت‌های اضافه یا فاصله باشد، در غیر اینصورت خطای «Error connecting to the server: malformed» ایجاد خواهد شد.

- changelogurl (اختیاری) 

  لینک به یک فایل XML که شامل لیست تغییرات (Changelog) نسخه است. از جوملا 4 به بعد، در صفحه آپدیت افزونه دکمه‌ای برای مشاهده لیست تغییرات نمایش داده می‌شود که این لینک به آن متصل است.

- tags (اختیاری) 

  لیستی از برچسب‌هایی که سطح پایداری نسخه را مشخص می‌کند. جوملا بر اساس این برچسب‌ها، وضعیت نسخه را در سیستم نمایش می‌دهد. برچسب‌های معتبر: 

  - `dev` : نسخه توسعه، بسیار ناپایدار (مثلاً ساخت‌های شبانه) 

  - `alpha` : نسخه آلفا، با ویژگی‌های ناقص و اشکالات بحرانی 

  - `beta` : نسخه بتا، قابلیت‌ها پیاده‌سازی شده ولی امکان اشکالات متوسط هست 

  - `rc` : نسخه کاندید انتشار، بدون اشکال بحرانی ولی ممکن است اشکالات جزئی داشته باشد 

  - `stable` : نسخه پایدار برای تولید و استفاده عمومی 

  اگر چند برچسب داده شود، فقط آخرین برچسب معتبر در نظر گرفته می‌شود. 

  اگر برچسبی داده نشود، جوملا فرض می‌کند نسخه پایدار است.

- maintainer (اختیاری) 

  نام نگهدارنده افزونه، مشابه تگ `<author>` در فایل manifest.

- maintainerurl (اختیاری) 

  لینک وب‌سایت نگهدارنده، مشابه تگ `<authorUrl>` در فایل manifest.

- section (اختیاری) 

  کاربرد مشخصی ندارد (معمولاً استفاده نشده).

- targetplatform (اجباری برای تعیین سازگاری) 

  مشخصات پلتفرم میزبان افزونه که باید شامل موارد زیر باشد: 

  - `name` 

    نام پلتفرم میزبان، فقط مقدار مجاز `"joomla"` است. 

  - `version` 

    نسخه یا نسخه‌های مجاز جوملا که افزونه روی آن‌ها کار می‌کند. می‌تواند به شکل عبارت منظم (regex) باشد. مثال‌ها: 

    - `version="4.[1234]"` → سازگار با نسخه‌های 4.1 تا 4.4 

    - `version="4.(2|4)"` → فقط سازگار با 4.2 و 4.4 

  - `min_dev_level` و `max_dev_level` (اختیاری) 

    این‌ها برای مشخص کردن بازه نسخه توسعه (development level) هستند، یعنی قسمت سوم نسخه (x.y.z). اگر وارد نشود، تمام سطوح توسعه پذیرفته می‌شوند. 

    مثال: 

<targetplatform name="joomla" version="4.0" min_dev_level="0" max_dev_level="1" />

این به معنی سازگاری با نسخه‌های 4.0.0 و 4.0.1 است.

- php_minimum (اختیاری) 

  حداقل نسخه مورد نیاز PHP برای نصب افزونه. اگر نسخه PHP سرور کمتر باشد، هنگام به‌روزرسانی به کاربر پیغامی داده می‌شود که نسخه جدید موجود است ولی قابل نصب نیست بخاطر نیازمندی‌های ناکافی.

خلاصه نمونه متداول `<targetplatform>` و چک نسخه PHP

<targetplatform name="joomla" version="4.[234]" min_dev_level="0" max_dev_level="9" />
<php_minimum>8.0</php_minimum>

 

- supported_databases – حداقل پایگاه‌های داده پشتیبانی شده + بررسی نسخه می‌تواند در جریان به‌روزرسانی ارائه شود. هنگامی که سرور حداقل را برآورده نمی‌کند، پیامی به کاربر نمایش داده می‌شود که به او اطلاع می‌دهد به‌روزرسانی موجود است اما به دلیل الزامات پشتیبانی نشده، قابل نصب نیست. به عنوان مثال:

<supported_databases mysql="5.5.3" mariadb="10.1" postgresql="9.2" mssql="10.50.1600.1" />

- sha256، sha384، sha512 - اختیاری. مجموع کنترلی فایل افزونه قابل دانلود، در این قالب‌های هش مختلف. اگر مجموع کنترلی ارائه شده مطابقت نداشته باشد، به‌روزرسانی متوقف می‌شود. می‌توانید ابزارهای آنلاین برای تولید این مجموع‌های کنترلی پیدا کنید.

مقادیر element، type و folder باید با مقادیر موجود در جدول `#__extensions` مطابقت داشته باشند، و client_id در آنجا باید با client مطابقت داشته باشد (0 برای site، 1 برای administrator).

نکته‌ی مهم برای پلاگین ‌ها: پلاگین ها برای عملکرد صحیح باید عناصر <folder> و <client> را داشته باشند.