قابلیت web assetsدر جوملا 4 اضافه شده است و به توسعه دهندگان و طراحان افزونه های جوملا این امکان را می دهد که از طریق ایجاد وابستگی بین فایل های CSS و JS مختلف، تنها فایل های مورد نیاز را در رندر نهایی صفحه بارگذاری کنند. این کار علاوه بر کاهش ریکوئست های سرور، از بارگذاری فایل های اضافه که در آن صفحه مورد نیاز نیست جلوگیریکرده و سرعت بارگذاری سایت رو بهبود می بخشد.
در ادامه ترجمه کامل کار با web assets را که از سایت رسمی جوملا جمعآوری شده خواهید خواند. توجه داشته باشید که این مقاله در چند نوبت و به مرور تکمیل و ویرایش می شود.
Web assets یا دارایی های وب
مفهوم
در دنیای فرانت‌اند، بسیاری از دارایی‌ها به هم مرتبط هستند. به عنوان مثال اسکریپت keepalive ما برای مدیریت گزینه ها به فایل core.js بستگی دارد. در جوملا هرگز راه آسانی برای مشخص کردن آن وجود نداشت، فقط باید چندین فایل را شامل می‌شد. جوملا 4 این را با مفهوم دارایی های وب تغییر می دهد.
تعریف
دارایی های مرتبط در یک فایل JSON مانند system/joomla.asset.json#L14-L21 تعریف می شوند.
این ساختار دارای یک تعریف schema (برای اعتبار سنجی)، name، version، license و سپس یک یا چند تعریف assets است. دارایی ها از لیستی از فایل های js و فایل های css مربوط به دارایی ها و هر گونه وابستگی تشکیل شده است. بخش وابستگی‌ها فقط فهرستی از نام‌های دارایی است که برای عملکرد دارایی مورد نیاز است. مثال:
{
"$schema": "https://developer.joomla.org/schemas/json-schema/web_assets.json",
"name": "com_example",
"version": "4.0.0",
"description": "Joomla CMS",
"license": "GPL-2.0+",
"assets": [
{
"name": "bar",
"type": "style",
"uri": "com_example/bar.css"
},
{
"name": "bar",
"type": "script",
"uri": "com_example/bar.js"
},
{
"name": "beer",
"type": "style",
"uri": "com_example/beer.css",
"dependencies": [
"bar"
],
},
{
"name": "beer",
"type": "script",
"dependencies": [
"core",
"bar"
],
"uri": "com_example/beer.js",
"attributes": {
"defer": true,
"data-foo": "bar"
}
}
]
}ویژگی schema$ یک فایل تعریف schema است که به شما امکان می دهد فایل خود را با استفاده از JSON Schema اعتبار سنجی کنید. برای کسب اطلاعات بیشتر در مورد کارهای اعتبار سنجی schema json، وب سایت رسمی را بخوانید.
توجه: داشتن joomla.asset.json برای افزونه ها یا قالب هایتان توصیه می شود، اما برای کار به WebAssset نیاز نیست (به بخش بعدی مراجعه کنید).
توجه: اضافه کردن دارایی درون خطی به فایل json توصیه نمی شود، ترجیحا از یک فایل استفاده کنید.
توضیح مراحل دارایی
هر دارایی دارای 2 مرحله است: ثبت شده و استفاده شده.
ثبت شده جایی است که یک دارایی در WebAssetRegistry بارگذاری می شود. این بدان معناست که WebAssetManager از وجود این دارایی ها اطلاع دارد، اما آنها را در حین رندر به سند ضمیمه نمی کند. تمام دارایی های بارگیری شده از joomla.asset.json در مرحله ثبت است.
استفاده شده جایی است که یک دارایی از طریق ()wa→useAsset$
(->useScript()، ->useStyle()، ->registerAndUseX() و غیره)
فعال می‌شود. این بدان معناست که WebAssetManager این دارایی‌ها و وابستگی‌های آنها را در حین رندر به یک سند متصل می‌کند.
اگر دارایی قبلا ثبت نشده باشد، نمی توان از آن استفاده کرد، این باعث ایجاد یک دارایی مستثنی ناشناخته می شود.
ثبت یک دارایی
همه دارایی های شناخته شده بارگیری و سپس در WebAssetRegistry ذخیره می شوند (برای فعال/غیرفعال کردن یک مورد دارایی باید از WebAssetManager استفاده کنید، بخش بعدی را ببینید).
جوملا به طور خودکار در زمان اجرا (به ترتیب زیر) به دنبال تعریف دارایی های بعدی خواهد بود:
media/vendor/joomla.asset.json (on first access to WebAssetRegistry)
media/system/joomla.asset.json
media/legacy/joomla.asset.json
media/{com_active_component}/joomla.asset.json (on dispatch the application)
templates/{active_template}/joomla.asset.jsonو آنها را در رجیستری دارایی های شناخته شده بارگذاری می کند.
توجه: هر تعریف دارایی زیر، اقلام دارایی را از تعریف دارایی های قبلی، بر اساس نام مورد، لغو می کند.
شما می توانید تعریف دارایی خود را از طریق WebAssetRegistry ثبت کنید:
/** @var Joomla\CMS\WebAsset\WebAssetManager $wa */
$wa = Factory::getApplication()->getDocument()->getWebAssetManager();
$wr = $wa->getRegistry();
$wr→addRegistryFile('relative/path/to/your/joomla.asset.json');برای افزودن یک مورد دارایی دلخواه در زمان اجرا:
$wr->add('script', new Joomla\CMS\WebAsset\WebAssetItem('foobar', 'com_foobar/file.js', ['type' => 'script']));یا ساده تر، با استفاده از WebAssetManager:
$wa->registerScript('foobar', 'com_foobar/file.js');foobar یک دارایی جدید به رجیستری دارایی های شناخته شده اضافه می شود، اما تا زمانی که کد شما (یک چیدمان، قالب و غیره) آن را درخواست نکند، به سند پیوست نمی شود.
برای بررسی اینکه آیا دارایی وجود دارد یا خیر:
if ($wa->assetExists('script', 'foobar'))
{
var_dump('Script "foobar" exists!');
}فعال کردن یک دارایی
تمام مدیریت دارایی توسط WebAssetManager در سند فعلی ، که با $doc->getWebAssetManager(); در دسترس هستند با استفاده از AssetManager می توانید به راحتی دارایی مورد نیاز را از طریق روش استاندارد جوملا فعال یا غیرفعال کنید.
برای فعال کردن یک دارایی در صفحه از تابع useAsset استفاده کنید، به عنوان مثال:
/** @var Joomla\CMS\WebAsset\WebAssetManager $wa */
$wa = Factory::getApplication()->getDocument()->getWebAssetManager();
$wa->useScript('keepalive');
// Or multiple
$wa->useScript('keepalive')
->useScript('fields.validate')
->useStyle('foobar')
->useScript('foobar');
// Add new asset item with dependency and use it
$wa->registerAndUseScript('bar', 'com_foobar/bar.js', [], [], ['core', 'foobar']);WebAssetManager به WebAssetRegistry نگاه می کند که آیا دارایی درخواستی وجود دارد یا خیر، و آن را برای نمونه سند فعلی فعال می کند. در غیر این صورت یک UnknownAssetException پرتاب می کند.
برای غیرفعال کردن یک دارایی در صفحه از تابع disableAsset استفاده کنید. مثال زیر بارگذاری دارایی jquery-noconflict را غیرفعال می کند.
/** @var Joomla\CMS\WebAsset\WebAssetManager $wa */
$wa = Factory::getApplication()->getDocument()->getWebAssetManager();
$wa→disableScript('jquery-noconflict');توجه: اگر وابستگی هایی به دارایی غیرفعال وجود داشته باشد، بدون توجه به هر چیزی، این دارایی به طور خودکار دوباره فعال می شود.
برای بررسی فعال بودن دارایی و وضعیت دارایی:
// Checking whether an asset are active (enabled manually or automatically as dependency)
if ($wa->isAssetActive('script', 'foobar'))
{
var_dump('Script "foobar" is active!');
}
// Checking state
switch($wa->getAssetState('script', 'foobar')){
case Joomla\CMS\WebAsset\WebAssetManager::ASSET_STATE_ACTIVE:
var_dump('Active! Was enabled manually');
break;
case Joomla\CMS\WebAsset\WebAssetManager::ASSET_STATE_DEPENDENCY:
var_dump('Active! Was enabled automatically while resolving dependencies');
break;
default:
var_dump('not active!');
}نادیده گرفتن یک دارایی
زمانی که نیاز دارید URI مورد دارایی یا وابستگی‌های آن را مجدداً تعریف کنید، لغو ممکن است مفید باشد. همانطور که قبلاً ذکر شد، هر یک از تعریف دارایی‌های زیر از joomla.asset.json، اقلام دارایی را از تعاریف دارایی‌های قبلی، با نام مورد لغو می‌کند. این بدان معناست که اگر joomla.asset.json را ارائه دهید که شامل موارد دارایی از قبل بارگیری شده است، آنها با موارد شما جایگزین می شوند. یکی دیگر از راه‌های لغو کد، ثبت یک مورد با همین نام است. به عنوان مثال، ما اسکریپت "foobar" داریم که کتابخانه com_example/foobar.js را بارگیری می کند، و می خواهیم از CDN برای این کتابخانه استفاده کنیم:
نحوه تعریف آن در ابتدا در سیستم
...
{
"name": "foobar",
"type": "script",
"uri": "com_example/foobar.js",
"dependencies": ["core"]
}
…برای لغو URI، آیتم دارایی را با نام "foobar" در joomla.asset.json خود تعریف می کنیم:
..
{
"name": "foobar",
"type": "script",
"uri": "http://foobar.cdn.blabla/foobar.js",
"dependencies": ["core"]
}
…
یا، مورد دارایی جدید را با AssetManager ثبت کنید:
$wa->registerScript('foobar', 'http://fobar.cdn.blabla/foobar.js', [], [], ['core']);کار با سبک ها
