بیان خلاصه ای از بحث توسط هوش مصنوعی:
قالب های چایلد یکی از بهترین ویژگی های معرفی شده در جوملا 4.1 هستند و به درخواست دیرینه کاربران جوملا برای داشتن یک پلتفرم انعطاف پذیر تر پاسخ می دهند.
قبل از ظاهر شدن قالب های چایلد، می توانید یک قالب سایت را شبیه سازی کنید و آن را برای رفع نیازهای خود ویرایش کنید، اما مدیریت بروزرسانی دشوار بود، زیرا باید با در نظر گرفتن تغییرات خود، یک بسته بروزرسانی برای کلون خود ایجاد کنید. قالب های چایلد این مشکل را برطرف می کنند و جایگزین مناسب کپی کردن همه فایل های یک قالب می شوند.
در این فصل، ما قصد داریم قالب چایلد خود را از قالب Cassiopeiaجوملا ایجاد کنیم. این به ما اجازه می دهد تا هنگام توسعه برنامه های وب سفارشی خود، انعطاف پذیری کامل داشته باشیم. ما می توانیم قالب های چایلد را تا جایی که نیاز داریم تغییر دهیم و موقعیت های ماژول های آنها را تغییر دهیم یا حتی دارایی ها را جایگزین کنیم. خواهیم دید که چگونه قالب هایی را شناسایی کنیم که به قالب های چایلد اجازه می دهند، نحوه مدیریت override در قالب های چایلد، و در نهایت، چگونه می توانیم از قالب های چایلد خود در سایت های دیگر استفاده مجدد کنیم.
برای یادگیری همه چیز در مورد قالب های چایلد در جوملا، ما این مسیر را دنبال می کنیم:
- چرا به قالب های چایلد نیاز داریم؟
- ایجاد یک قالب چایلد
- اضافه کردن یک موقعیت ماژول جدید به قالب
- استفاده مجدد از قالب های چایلد در سایت های مختلف
الزامات فنی
در این فصل، ما قصد داریم به ساختار کدنویسی خود بازگردیم، بنابراین به موارد زیر نیاز خواهید داشت:
- Visual Studio Code (یا ویرایشگر کد دلخواه شما)
- سایت جوملا که در فصل های قبل نصب کردیم
- می توانید فایل های کد این فصل را در GitHub در آدرس زیر پیدا کنید:
https://github.com/PacktPublishing/Developing-Extensions-for-Joomla-5/tree/chapter11
چرا به قالب های چایلد نیاز داریم؟
در فصل 10 ، قدرت جوملا را برای ایجاد برنامه های کاربردی وب با طراحی سفارشی با override دیدیم. می توانیم از override قالب برای تغییر طراحی ناحیه کامپوننت، استایل های جدید، دارایی های جدید، بارگذاری فایل جاوا اسکریپت و انواع نماهای جدید برای منوهای خود استفاده کنیم. این ممکن است کافی به نظر برسد، اما چند نکته اضافی وجود دارد:
- با override، نمی توانیم ساختار اصلی سایت را تغییر دهیم، زیرا نمی توانیم موقعیت های قالب را ویرایش کنیم.
- با override، ما نمی توانیم دارایی های وب را برای کل سایت ویرایش کنیم، تغییرات ما محدود به مناطقی از سایت خواهد بود که در آن override انجام می شود.
- مهم تر از همه، ما نمی توانیم یک override را از یک override دیگر ایجاد کنیم. شما می توانید تنها یک override برای هر عنصر داشته باشید. این بسیار مهم است زمانی که قالب مورد استفاده شما از یک override قالب برای چیدمانی که می خواهید، استفاده می کند.
قالب های چایلد فایل ها و رفتار را از قالب والد خود به ارث می برند. این به ما امکان می دهد تا توسعه را بر روی حوزه هایی از قالب خود متمرکز کنیم که می خواهیم تغییر دهیم و بقیه ی موارد از والد استفاده می کند.
بنابراین، هنگامی که ما نیاز به اصلاح یک طرح از یک override داریم، می توانیم به سادگی یک قالب چایلد از قالب اصلی خود ایجاد کنیم و override جدید خود را در قالب چایلد ایجاد کنیم. این در هنگام استفاده از قالبی از توسعه دهنده دیگری که با الگوبرداری از قالب ارائه می شود، مفید است.
همانطور که میدانید، در جوملا، شما می توانید قالب های نامحدود، در هر سایت داشته باشید. این تکنیک به شما کمک می کند تا به همان اندازه که نیاز دارید، از همان عنصر override استفاده کنید.
ایجاد یک قالب چایلد
یک قالب اولیه چایلد، شامل یک بسته فایل XML در یک فایل ZIP است. خیلی ساده و خیلی قدرتمند. بدیهی است که نکته کلیدی در اینجا، محتوای آن فایل XML و نحوه اضافه کردن بقیه فایل های مورد نیاز است. و البته، وقتی تغییرات بیشتری به فایل خود اضافه می کنیم، همه چیز کمی پیچیده تر می شود.
این فایل XML مانیفست کاملاً شبیه فایل مانیفست قالب والد است. همچنین شبیه فایل های مانیفست دیگر افزونه هایی است که در فصل های قبلی دیدیم. بیایید شروع به ایجاد اولین قالب چایلد خود کنیم تا ببینیم چگونه ایجاد شده است. ابتدا باید یک قالب والد را برای ایجاد قالب چایلد، انتخاب کنیم. در این کتاب به چند دلیل قصد داریم از قالب Cassiopeia به عنوان قالب والد و اصلی استفاده کنیم:
- در هنگام نصب هر جوملا موجود است.
- Cassiopeia به استانداردهای وب احترام می گذارد و داوطلبان زیادی آن را در محیط های مختلف آزمایش کرده اند.
- Cassiopeia از نظر قابلیت دسترسی و قابلیت استفاده بسیار نمره ی خوبی دارد، بنابراین یک نقطه شروع عالی برای ایجاد یک قالب جدید عالی است.
هنگامی که تصمیم گرفتیم یک قالب چایلد از Cassiopeia ایجاد کنیم، باید بررسی کنیم که آیا این الگو به ما اجازه ایجاد یک قالب چایلد را می دهد یا خیر. برای دیدن این ویژگی، به فایل سایت جوملا خود به آدرس templates/cassiopeia/templateDetails.xml ، میرویم و ما به دنبال تگ inheritable میگردیم. مقدار محصور شده در تگ باید1 باشد ، مطابق این کد:
<copyright>(C) 2017 Open Source Matters, Inc.</copyright>
<description>TPL_CASSIOPEIA_XML_DESCRIPTION</description>
<inheritable>1</inheritable>
در این استخراج کد مانیفست، می توانیم برچسب 1 را همانطور که نیاز داریم برجسته کنیم، بنابراین می توانیم شروع به ایجاد قالب خود کنیم.
ایجاد یک قالب چایلد به طور مستقیم در مخزن ما
در مخزن کد خود، فایل src/templates/cassiopeia_first/templateDetails.xml را با محتوای زیر اضافه می کنیم:
<?xml version="1.0" encoding="UTF-8"?>
<extension type="template" client="site">
<name>cassiopeia_first</name>
<version>1.0</version>
<creationDate>August 2023</creationDate>
<author>Carlos</author>
<authorEmail>این آدرس ایمیل توسط spambots حفاظت می شود. برای دیدن شما نیاز به جاوا اسکریپت دارید </authorEmail>
<copyright>(C) 2023 Piedpiper</copyright>
<description>TPL_CASSIOPEIA_XML_DESCRIPTION</description>
<parent>cassiopeia</parent>
<inheritable>0</inheritable>
<positions>
<position>topbar</position>
<position>below-top</position>
<position>menu</position>
<position>search</position>
<position>banner</position>
<position>top-a</position>
<position>top-b</position>
<position>main-top</position>
<position>main-bottom</position>
<position>breadcrumbs</position>
<position>sidebar-left</position>
<position>sidebar-right</position>
<position>bottom-a</position>
<position>bottom-b</position>
<position>footer</position>
<position>debug</position>
</positions>
<files>
<filename>templateDetails.xml</filename>
</files>
</extension>
در این فایل XML، ما در حال تعریف عناصر اساسی قالب مان هستیم. اول از همه، در تگ اصلی، ویژگی type را روی extension قرار می دهیم. یک قالب چایلد یک قالب معمولی است. ما همچنین قالب را به عنوان یک قالب ظاهری با ویژگی client="site" تنظیم کردیم. در داخل هر تگ، تگ های ابرداده خود را اضافه می کنیم. در این حالت، همانطور که ما در حال ایجاد یک قالب چایلد هستیم، باید نام قالب چایلد خود را با نام قالب والد خود به صورت پیشوند قرار دهیم. در کد ما از cassiopeia_first استفاده می کنیم.
برای بقیه تگ های فراداده، version ، creationDate ، author ، authorEmail ، copyright و description ، ما آزادیم که اطلاعات مورد نظر خود را تنظیم کنیم.
پس از افزودن متادیتا، تگ را با نام قالب والد قرار داده ایم. این مهم است، زیرا جوملا، قالب والد را بررسی می کند تا همه فایل ها و اطلاعاتی را که در قالب چایلد خود قرار نمی دهیم، پر کند.
پس از تنظیم والد، می بینیم که تگ inheritable را روی0 پیکربندی کرده ایم، که نشان می دهد این الگو نمی تواند فرزندی داشته باشد. این بر اساس طراحی است، زیرا قالب های چایلد نمی توانند دارای فرزند باشند. ممکن است به تعداد مورد نیاز از الگوهای والد، قالب های چایلد ایجاد کنید، اما نمی توانید برای قالب چایلد یک قالب چایلد دیگر را ایجاد کنید.
پس از افزودن متادیتای قالب و تعیین قالب والد، می توانیم بخش موقعیت ها را ببینیم. این بخش در زیر تگ positions محصور شده است و در داخل آن، ما تمام موقعیت های موجود در قالب شما را برای استفاده برای ماژول ها قرار می دهیم. ما می توانیم از نام های مختلفی برای این موقعیت ها استفاده کنیم. پس از همه، ما در حال ایجاد یک قالب جدید هستیم، و همچنین می توانیم موقعیت ها را اضافه کنیم یا آنها را از لیست حذف کنیم. در هر صورت، توصیه من این است که نام را برای موقعیت های قالب والد نگه دارید و موقعیت های مورد نیاز خود را اضافه کنید. جوملا هنگام انتشار یک ماژول، از موقعیت های موجود در مانیفست استفاده می کند. با این حال، برای تصمیم گیری در جایی که آنها را قرار دهیم، باید مقداری کدنویسی را در موقعیت Adding a new module to the template قرار دهیم.
بعد از قسمت موقعیت ها ، قسمت فایل ها را پیدا می کنیم. این بخش شامل فایل ها و پوشه هایی است که باید روی سایت جوملا نصب شوند. ما قالب چایلد خود را فقط با فایل templateDetails.xml ایجاد می کنیم، بنابراین آن را در مانیفست خود قرار می دهیم.
این تنها فایلی است که برای ایجاد یک قالب چایلد نیاز داریم، بنابراین می توانیم آن را در یک فایل ZIP بسته بندی کنیم و از طریق مدیریت extension جوملا در سایت جوملای خود نصب کنیم. پس از نصب، می توانید این قالب چایلد را مانند هر قالب دیگری در سایت جوملا خود انتخاب کنید.
این یک قالب چایلد بسیار ابتدایی است، و صادقانه بگویم، چندان مفید نخواهد بود، زیرا هیچ چیز را در پیکربندی قالب والد تغییر نمی دهد. ما قصد داریم این قالب را در بخش های بعدی بهبود دهیم، اما در حال حاضر، می توانیم ببینیم که ایجاد این قالب چایلد ساده شامل سه مرحله است:
- ایجاد XML
- بسته بندی XML
- نصب پکیج در جوملا
زمانی که می خواهیم تغییراتی را در فایل های خود اعمال کنیم، مانند استایل های اضافی، override متفاوت یا توابع جاوا اسکریپت، این فرایند کمی پیچیده تر است.
در بخش بعدی، می خواهیم ببینیم که چگونه می توانیم یک قالب چایلد را تنها با کلیک بر روی یک دکمه بسازیم.
ایجاد یک قالب چایلد با استفاده از مدیریت قالب جوملا
در جوملا، می توانیم یک قالب چایلد را به طور مستقیم از مدیریت قالب ایجاد کنیم. برای این کار باید به مدیریت سایت جوملا خود وارد شوید و به System | Templates رفته و سپس، روی Cassiopeia Details and Files (یا لینک آنالوگ قالب مورد نظر برای ایجاد قالب چایلد) کلیک کنید. در نهایت بر روی دکمه Create Child Template کلیک می کنید. با کلیک بر روی دکمه، قالب چایلد ایجاد می شود و به صورت خودکار در سایت شما نصب می شود.
علاوه بر فایل templateDetails.xml ، جوملا پوشه های تغییرات را داخل templates/cassiopeia_first/html و پوشه های رسانه را ایجاد کرده است:
- media/templates/site/cassiopeia_first/css
- media/templates/site/cassiopeia_first/js
- media/templates/site/cassiopeia_first/images
- media/templates/site/cassiopeia_first/scss
بنابراین، ما می توانیم شروع به اضافه کردن override ها به طور مستقیم به این پوشه ها کنیم.
برای ایجاد این پوشه ها به صورت دستی، همانطور که در بخش قبل، ما باید پوشه ها را در ساختار مخزن خود ایجاد کنیم:
- src/templates/cassiopeia_first/html
- src/templates/cassiopeia_first/media/css
- src/templates/cassiopeia_first/media/js
- src/templates/cassiopeia_first/media/images
- src/templates/cassiopeia_first/media/scss
آنها را به بخش templateDetails.xml اضافه کنید :
<files>
<filename>templateDetails.xml</filename>
<folder>html</folder>
</files>
<media folder="media" destination="templates/site/cassiopeia_first">
<folder>css</folder>
<folder>js</folder>
<folder>images</folder>
<folder>scss</folder>
</media>
در بخش بعدی خواهیم دید که در یک قالب چایلد چه اتفاقی برای override ها گرفته می شود.
override در قالب های چایلد
جوملا هنگام استفاده از قالب چایلد، ابتدا سعی می کند فایل های را از پوشه های قالب چایلد پیدا کند و اگر فایلی در دسترس نباشد، فایل را از قالب والد بررسی می کند. این در مورد هر منبعی که نیاز به استفاده از آن داریم، صدق می کند.
با این حال، هنگامی که قالب والد ما یک جایگزین دارد که می خواهیم در قالب چایلد نگه داریم، نیازی نیست دوباره آن را در پوشه html قالب چایلد کپی کنیم. جوملا به طور خودکار از override موجود در پوشه html قالب والد استفاده می کند.
با این حال، زمانی که ما یک override در پوشه html قالب چایلد ایجاد می کنیم، اولویت دارد و جوملا از آن به جای هر چیز دیگری، استفاده می کند. این قضیه برای حفظ موارد override ما در برابر بروزرسانی های قالب والد در آینده، بسیار مفید است.
در فصل 10، متدی را دیدیم که از طریق مدیر دارایی های وب، دارایی ها را override کنیم. در واقع، ما فقط با استفاده از دارایی ها می توانستیم آنها را override بکنیم. با قالب های چایلد، می توانیم با ایجاد یک فایل در پوشه رسانه مناسب، دارایی ها را بدون Web Assets Manager ایجاد کنیم.
بیایید نمونه ای از این را با ایجاد یک override برای استایل ها در فایل offline.css ببینیم. فایل offline.css زمانی ظاهر می شود که از حالت آفلاین سایت جوملا استفاده می کنیم. به مسیر زیر رفته و Site Offline را فعال کنید:
Joomla administrator | Global Configuration | Site and enable the Site offline
اکنون وقتی به قسمت frontend سایت خود می روید، صفحه آفلاین پیش فرض Cassiopeia را مشاهده خواهید کرد.
حالا، از مدیریت قالب ها یا ویرایشگر کد خود استفاده کنید و فایل media/templates/site/cassiopeia_first/css/offline.css را با محتوای زیر اضافه کنید:
.logo-icon{
display: none;
}
.header{
background-color: #1E8d38;
padding: 2rem;
}
.outer{
margin: 2rem auto;
padding: 0rem 0 2rem 0;
border: 2px solid #1E8d38;
background-color: #2F9E49;
color: white;
}
.login{
padding: 1rem 2rem;
}
.btn{
background-color: #0d7e27;
border-color: #0d7e27;
color: white;
}
.btn:hover,
.btn:focus{
background-color: #1E8d38;
border-color: #1E8d38;
color: white;
outline-color: white;
}
این کد CSS ، ظاهر صفحه آفلاین را تغییر می دهد و آیکون جوملا را حذف می کند و رنگ پس زمینه را به سبز تغییر میدهد. از آنجایی که فایل CSS در داخل پوشه رسانه ما در قالب چایلد قرار دارد، بر فایل قالب پیش فرض Cassiopeia اولویت دارد. جوملا از آن برای تولید صفحه ی آفلاین استفاده می کند.
اضافه کردن یک موقعیت ماژول جدید به قالب
قالب های جوملا را می توان به مناطق یا موقعیت ها تقسیم کرد. این موقعیت ها محفظه هایی (container) هستند که جوملا، ماژول ها و کامپوننت ما را در بارگذاری صفحه در آنها قرار می دهد. به این ترتیب، یک قالب جوملا می داند که خروجی کامپوننت یا خروجی یک ماژول را کجا قرار دهد.
قبلا در این فصل دیدیم که این موقعیت ها در فایل templateDetails.xml گنجانده شده است. جوملا از موقعیت های موجود در این فایل مانیفست برای ارائه موقعیت های موجود هنگام ویرایش یک ماژول استفاده می کند. با این حال، آنچه که بسیار مهم است گنجاندن موقعیت در ساختار قالب است. موقعیت های قالب، در فایل اصلی قالب جوملا که فایل index.php قالب است کد نویسی شده است. اینجاست که ما تمام ساختارهای اولیه HTML را که قالب ما برای ایجاد صفحه وب خروجی استفاده می کند، تنظیم می کنیم.
برای سهولت در گنجاندن محتوای خروجی جوملا در این ساختار قالب، در جوملا، می توانیم از یک تگ HTML سفارشی، jdoc:include استفاده کنیم.
این تگ چندین ویژگی را می پذیرد:
- typeنوع محتوایی را از CMS که می خواهیم بارگیری کنیم را نشان می دهد. انواع محتوای اصلی که می توانیم استفاده کنیم عبارتند از:
§ head
§ component
§ modules
§ message
(لینکی به اسناد رسمی اظهارات jdoc در بخش خواندن بیشتر این فصل وجود دارد.)
- name این ویژگی فقط زمانی اعمال می شود که ما در حال بارگذاری موقعیت ماژول هستیم. به جوملا نام موقعیت ماژول برای بارگیری را می گوید.
- style این ویژگی به جوملا می گوید که از کدام استایل یا کروم (chrome) برای ایجاد خروجی ماژول، استفاده شود.
همچنین می توانیم از ویژگی های بیشتری برای نوع محتوایی که بارگذاری می کنیم، استفاده کنیم.
بیایید یک موقعیت afterfooter جدید به قالب چایلد خود اضافه کنیم. فایل را از سایت جوملا خود در آدرس templates/cassiopeia/index.php ، به templates/cassiopeia_first/ کپی کنید. فایل را ویرایش کنید و در پایین آن ممکن است کد زیر را مشاهده کنید:
<?php if ($this->countModules('footer', true)) : ?>
<footer class="container-footer footer full-width">
<div class="grid-child">
<jdoc:include type="modules" name="footer" style="none" />
</div>
</footer>
<?php endif; ?>
زیر آن کد، کد زیر را اضافه کنید:
<?php if ($this->countModules('afterfooter', true)) : ?>
<div class="container-afterfooter afterfooter full-width">
<div class="grid-child">
<jdoc:include type="modules" name="afterfooter" style="none" />
</div>
</div>
<?php endif; ?>
در این کد ابتدا از متد countModules که توسط فریم ورک جوملا (Joomla Framework TM) ارائه شده است استفاده می کنیم. این متد تعداد ماژول های اضافه شده را به موقعیت afterfooter بر می گرداند. همانطور که آرگومان دوم را به عنوان true پاس می کنیم، متد فقط ماژول هایی را بر می گرداند که هر محتوایی را خروجی می دهند.
پس از شناسایی محتوا، یک ساختار اولیه HTML برای نمایش ماژول های خود ایجاد می کنیم و در نهایت از تگ استفاده می کنیم. برای ویژگی های برچسب از نام afterfooter که نام موقعیت جدید است و برای ویژگی style از none استفاده می کنیم. این ماژول را بدون استایل خاصی به طور پیش فرض خروجی می دهد. این را می توان هنگام پیکربندی ماژول در backend تغییر داد ، همانطور که در بخش بعدی خواهیم دید.
برای آزمایش این، می توانیم به ناحیه مدیریت جوملا خود برویم، یک ماژول جدید از نوع Copyright ایجاد کرده و آن را به موقعیت afterfooter اختصاص دهید.
بیایید اکنون ببینیم که چگونه می توانیم استایل های متفاوتی برای ماژول های قالب خود ایجاد کنیم.
استفاده از استایل های مختلف برای ماژول
هنگام بررسی در صفحه پیکربندی ماژول، ممکن است در برگه Advanced چندین گزینه مانند Module Class ، Header Tag و Module Style را بیابید. این گزینه ها، کد خروجی ماژول را تغییر می دهند، مانند افزودن کلاس CSS، تغییر تگ هدر، یا استفاده از استایل یا چیدمان متفاوت برای خروجی.
هنگام توسعه یک قالب، می توانید استایل های ماژول(module styles) مختلف را برای ماژول های خود ایجاد کنید، یا آنهایی که قبلا ایجاد شده اند را override کنید. در واقع، یکی از ویژگی هایی که هنگام اضافه کردن یک ماژول تنظیم می کنیم، استایلی است که می خواهیم به طور پیش فرض از آن استفاده کنیم.
استایل های ماژول به عنوان ماژول کروم (module chromes) ، و ما آنها را در داخل پوشه override قالب خود تعریف می کنیم (به طور خاص، در مسیر html/layouts/chromes/ ) اگر این پوشه را برای قالب Cassiopeia خود بررسی کنید، خواهید دید که در حال حاضر 2 فایل وجود دارد، card.php و noCard.php.
بیایید یک استایل ماژول برای قالب چایلد خود ایجاد کنیم و فایل /templates/cassiopeia_first/html/layouts/titleCentered.php را با محتوای زیر اضافه کنیم:
<?php
use Joomla\Utilities\ArrayHelper;
$module = $displayData['module'];
$params = $displayData['params'];
$attribs = $displayData['attribs'];
if ($module->content === null || $module->content === '') {
return;
}
$moduleTag = $params->get('module_tag', 'div');
$moduleAttribs = [];
$moduleAttribs['class'] = $module->position . ' no-card ' . htmlspecialchars($params->get('moduleclass_sfx', ''), ENT_QUOTES, 'UTF-8');
$headerTag = htmlspecialchars($params->get('header_tag', 'h3'), ENT_QUOTES, 'UTF-8');
$headerClass = htmlspecialchars($params->get('header_class', ''), ENT_QUOTES, 'UTF-8');
$headerAttribs = [];
$headerAttribs['class'] = 'text-center';
if ($headerClass !== '') {
$headerAttribs['class'] = ' ' . $headerClass;
}
if ($moduleTag !== 'div') {
if ($module->showtitle) :
$moduleAttribs['aria-labelledby'] = 'mod-' . $module->id;
$headerAttribs['id'] = 'mod-' . $module->id;
else :
$moduleAttribs['aria-label'] = $module->title;
endif;
}
$header = '<' . $headerTag . ' ' . ArrayHelper::toString($headerAttribs) . '>' . $module->title . '</' . $headerTag . '>';
?>
<<?php echo $moduleTag; ?> <?php echo ArrayHelper::toString($moduleAttribs); ?>>
<?php if ($module->showtitle) : ?>
<?php echo $header; ?>
<?php endif; ?>
<?php echo $module->content; ?>
</<?php echo $moduleTag; ?>>
این کد بر اساس استایل ماژول noCard.php است. با این استایل، محتوای ماژول خود را در module tag انتخاب شده توسط کاربر، قرار می دهیم، با تغییر کوچک در مرکز عنوان ماژول، وقتی نشان داده می شود.
پس از تعریف فضاهای نام، داده های ماژول را از آرایه $displayData دریافت می کنیم. از این آرایه، سه متغیر با تمام اطلاعات ماژول دریافت می کنیم:
- $module این شامل تمام اطلاعات ماژول، مانند محتوای ماژول برای نمایش، عنوان، و همچنین پارامترهای ماژول است.
- $params این شامل تمام تنظیماتی است که کاربر در پیکربندی ماژول تنظیم می کند.
- $attribs این شامل ویژگی های اصلی ماژول، مانند نام موقعیت و نام استایل مورد استفاده است.
از این متغیرها، ابتدا بررسی می کنیم که آیا ماژول محتوایی را خروجی می دهد یا خیر و در غیر این صورت بر میگردیم. هنگامی که ماژول حاوی اطلاعاتی برای نمایش است، ما پارامترهای ماژول را بررسی می کنیم تا کد HTML حاصل را تعریف کنیم.
ما ویژگی های تگ هدر را در آرایه $headerAttribs و ویژگی های ظرف ماژول را در آرایه $moduleAttribs گروه بندی می کنیم. به این ترتیب، می توانیم از متد ArrayHelper::toString() برای تولید آسان کد HTML استفاده کنیم.
تغییر ما در این کد شامل اضافه کردن کلاس text-center به مقادیر $headerAttribs['class'] است تا زمانی که نشان داده شود عنوان توسط کلاس فوق در مرکز قرار گیرد. این کلاس CSS از Bootstrap 5 پیروی میکند.
ما می توانیم از این استایل در هنگام اضافه کردن ماژول خود، با استفاده از آن تگ، به صورت زیر استفاده کنیم:
<jdoc:include type="modules" name="afterfooter" style="titleCentered" />
در بخش بعدی خواهیم دید که چگونه می توانیم قالب چایلد خود را در سایت های دیگر استفاده کنیم.
استفاده مجدد از قالب های چایلد در سایت های مختلف
ایجاد قالب های چایلد با استفاده مدیریت قالب جوملا، (همانطور که در بخش های قبلی این فصل مشاهده شد)، ساده ترین راه برای ایجاد قالب چایلد است. همچنین ممکن است برای شما راحت باشد که تغییرات قالب چایلد خود را ایجاد کنید و مستقیماً روی سایت جوملا خود override کنید. وقتی می خواهیم از این قالب های چایلد در سایت های دیگر استفاده ی مجدد کنیم، به راهی برای انتقال تغییرات خود نیاز داریم. خوشبختانه، می توانیم از قالب های چایلد در سایت هایی که نیاز داریم، دوباره استفاده کنیم. تنها شرط این است که در سایت جدید باید قالب والد را از قبل نصب کرده باشیم.
ساده ترین راه برای استفاده مجدد از قالب چایلد خود در چندین سایت، ایجاد یک بسته قابل نصب است. از آنجایی که ما قبلاً فایل templateDetails.xml خود را داریم، فقط باید فایل ها را به روشی مناسب برای ایجاد آنها بسته بندی کنیم.
دو پوشه مختلف وجود دارد که باید به آنها توجه کنید، پوشه قالب اصلی و پوشه رسانه (در صورتی که تغییراتی به آن اضافه کرده باشید). برای آسان تر کردن فرآیند، بیایید قالب چایلد اصلی خود را در مخزن کد خودمان کپی کنیم و از آنجا، بسته خود را ایجاد می کنیم.
اگر قالب اصلی چایلد شما در سایت جوملا روی یک سرور راه دور است، برای دانلود فایل ها در مخزن کد خود باید از FTP یا ابزاری مشابه استفاده کنید.
*برای سهولت کار در این فصل، به جای دانلود فایل ها، از فعل کپی استفاده می کنیم.
ابتدا به پوشه قالب های سایت جوملا خود بروید و محتوای پوشه templates/cassiopeia_first/ را در مخزن محلی (local) ما در مسیر src/templates/cassiopeia_first کپی کنید.
اگر دارایی هایی را نیز به پوشه ی رسانه اضافه کرده اید یا تغییر داده اید، باید آنها را کپی کنید. بنابراین، محتویات پوشه را از سایت جوملا خود در media/templates/site/cassiopeia_first به src/templates/cassiopeia_first/media/ کپی کنید.
برای ایجاد بسته قالب چایلد خود، باید پوشه src/templates/cassiopeia_first/ را با تمام محتوای آن Zip کنید. همچنین، اگر به دقت بررسی کنید، باید فایل templateDetails.xml را با پوشه های html و media داخل بسته داشته باشید.
اگر برای فایل index.php یا offline.php ، یک override ایجاد کرده اید، باید فایل مانیفست templateDetails.xml را ویرایش کرده و مطابق با آن به بخش مربوطه اضافه کنید، مانند موارد زیر:
<files>
<filename>templateDetails.xml</filename>
<filename>index.php</filename>
<filename>offline.php</filename>
<folder>html</folder>
</files>
<media folder="media" destination="templates/site/cassiopeia_first">
<folder>css</folder>
<folder>js</folder>
<folder>images</folder>
<folder>scss</folder>
</media>
همچنین می توانید هر یک از پوشه های خالی این قسمت را حذف کنید.
این به شما امکان می دهد قالب چایلد خود را روی هر سایت جوملا با قالب Cassiopeia نصب کنید.
*البته، اگر شما در فرایند ساخت از قالب والد دیگری استفاده کرده اید، این فایل برای شما کار می کند.
ما قالب چایلدی ایجاد کرده ایم که می توانیم در چندین سایت دوباره از آن استفاده کنیم و حتی آن را بین سایر کاربران جوملا توزیع کنیم. با این حال، وقتی پیکربندی قالب چایلد را در مدیریت جوملا می بینید، خواهید دید که مطلقا هیچ پارامتری برای پیکربندی وجود ندارد.
در بخش بعدی، اضافه کردن پارامترها به قالب چایلد خود را برای پیکربندی، راحت تر خواهیم کرد.
افزودن پارامترها به قالب چایلد
بنابراین، ما هیچ پارامتری برای پیکربندی در قسمت مدیریت قالب چایلد نداریم. در قالب والد، پارامترهایی برای نشان دادن لوگو یا انتخاب چیدمان وجود دارد. چرا این اتفاق می افتد؟ قالب های چایلد پارامترهای انتخاب شده را از والدین خود به ارث می برند، حتی اگر هیچ پارامتری در قسمت پیکربندی نداشته باشند.
با این حال، از آنجایی که قالب های چایلد، قالب های کاملی هستند، می توانند پارامترها و تنظیمات خاص خود را داشته باشند و در واقع می توانند با قالب والد خود متفاوت باشند.
برای افزودن یک پارامتر به قالب چایلد، باید بخشی را به فایل templateDetails.xml اضافه کنیم، همانطور که با سایر افزونه ها در فایل مانیفست آنها انجام دادیم. از آنجایی که قالب ما از برخی از تنظیمات والد خود استفاده می کند، جالب است که این پارامترها را دوباره به تنظیمات اضافه کنیم. در مورد ما، ما قصد داریم تنظیمات مربوط به لوگو و برند را اضافه کنیم. بنابراین، فایل src/templates/cassiopeia_first/templateDetails.xml را ویرایش کنید و کد زیر را قبل از بسته شدن تگ اضافه کنید:
<config>
<field name="brand" type="radio" label="TPL_CASSIOPEIA_BRAND_LABEL" default="1" layout="joomla.form.field.radio.switcher" filter="boolean">
<option value="0">JNO</option>
<option value="1">JYES</option>
</field>
<field name="logoFile" type="media" default="" label="TPL_CASSIOPEIA_LOGO_LABEL" showon="brand:1"/>
<field name="siteTitle" type="text" default="" label="TPL_CASSIOPEIA_TITLE" filter="string" showon="brand:1"/>
<field name="siteDescription" type="text" default="" label="TPL_CASSIOPEIA_TAGLINE_LABEL" description="TPL_CASSIOPEIA_TAGLINE_DESC" filter="string" showon="brand:1"/>
</config>
این کد بخشی را اضافه می کند که تنظیمات قالب ما را نگه می دارد. این فیلدها از Cassiopeia قالب والد ما کپی شده اند و به ما اجازه می دهد لوگو را تغییر دهیم و عنوان و یک برچسب برای وب سایت تعریف کنیم.
وقتی قالب چایلد را با این تغییرات نصب می کنید، میتوانید از مسیر زیر و تب Advanced وارد تنظیمات قالب شوید:
System | Template styles | cassiopeia_first
در تب Advanced، این چهار تنظیمات را برای پیکربندی پیدا خواهید کرد.
این تنظیمات همان نام تنظیمات در قالب والد هستند و مقادیری که در اینجا انتخاب می کنید، مقادیر تنظیم شده در قالب والد را override می کنند.
اکنون زمان آن است که قالب چایلد خود را کمی متفاوت تر کنیم، بنابراین می خواهیم یک دکمه سوئیچ را برای وسط لوگو اضافه کنیم. برای انجام این کار، فایل templateDetails.xml را که به تازگی ویرایش کرده اید، ویرایش کنید و فیلد زیر را قبل از بسته شدن تگ اضافه کنید:
<field name="logoCentered" type="radio" label="TPL_CASSIOPEIA_FIRST_LOGOCENTERED" default="0"
layout="joomla.form.field.radio.switcher" filter="boolean">
<option value="0">TPL_CASSIOPEIA_FIRST_LOGO_NOT_CENTERED</option>
<option value="1">TPL_CASSIOPEIA_FIRST_LOGO_CENTERED</option>
</field>
این کد یک دکمه ی رادیو اضافه می کند که کاربر می تواند لوگو را در مرکز وب سایت انتخاب کند. اکنون باید کدی را به قالب چایلد اضافه کنیم که از این تنظیمات استفاده می کند. برای انجام این کار، فایل src/templates/cassiopeia_first/index.php را ویرایش می کنیم و کد زیر را بعد از تعریف متغیر $ wa قرار می دهیم:
if ($this->params->get('logoCentered', false)) {
$wa->addInlineStyle(".container-header .navbar-brand{ margin:auto}");
}
این کد تنظیمات ذخیره شده از فیلد logoCented را دریافت می کند و اگر true باشد، ما از Web Assets Manager و متغیر $wa برای اضافه کردن استایل های css استفاده می کنیم که باید لوگو را به عنوان یک استایل درون خطی، در مرکز قرار دهد.
هنگام استفاده پارامترها از قالب والد، جوملا از رشته های زبان والد استفاده می کند، اما وقتی از پارامترهای جدید استفاده می کنیم، باید به جوملا بگوییم که ترجمه های این رشته ها چیست.
در بخش بعدی، می خواهیم ببینیم که چگونه رشته های زبان خود را به یک قالب چایلد اضافه کنیم.
افزودن فایل های زبان به قالب چایلد
قالب چایلد تمام جنبه های والد خود را به ارث می برد و این شامل فایل های زبان و ترجمه نیز می شود. با این حال، وقتی رشته های زبانی را به قالب چایلد خود اضافه می کنیم که در والد گنجانده نشده است، باید ترجمه های معادل آنها را اضافه کنیم.
در مثال ما، باید چند رشته زبان جدید را به قالب چایلد خود اضافه کنیم. برای انجام این کار، فایل ها را از جوملا در آدرس های زیر کپی کرده و به فایل خود یا مخزن اضافه کنید:
از
language/en-GB/tpl_cassiopeia.ini
language/en-GB/tpl_cassiopeia.sys.ini
به
src/templates/language/en-GB/tpl_cassiopeia_first.ini
src/templates/language/en-GB/tpl_cassiopeia_first.sys.ini.
سپس، خطوط زیر را به src/templates/language/en-GB/tpl_cassiopeia_first.ini اضافه می کنیم.
TPL_CASSIOPEIA_FIRST_LOGOCENTERED="Logo position"
TPL_CASSIOPEIA_FIRST_LOGO_CENTERED="Centered"
TPL_CASSIOPEIA_FIRST_LOGO_NOT_CENTERED="Left aligned"
باید ترجمه های زبان قبلی را کپی کنیم تا از دست ندهیم. جوملا تا زمانی که قالب چایلد خود فایل زبانی نداشته باشد از یک فایل زبان مادر استفاده می کند. زمانی که قالب چایلد یک فایل زبان روی سایت نصب کرد، جوملا جستجوی فایل های زبان قالب والد را متوقف می کند و فقط از ترجمه های قالب چایلد استفاده می کند.
در نهایت باید فایل های زبان اخیرا ایجاد شده را به مانیفست قالب چایلد اضافه کنیم تا همراه با قالب ما نصب شوند. بنابراین، فایل src/templates/cassiopeia_first/templateDetails.xml را ویرایش کنید و خطوط زیر را در زیر بخش اضافه کنید:
<languages folder="language">
<language tag="en_GB">en-GB/tpl_cassiopeia_first.ini</language>
<language tag="en_GB">en-GB/tpl_cassiopeia_first.sys.ini </language>
</languages>
این به جوملا دستور می دهد تا فایل زبان را نصب کند.
اکنون، پس از نصب قالب، می توانیم تنظیمات پارامتر خود را به طور کامل ترجمه شده ببینیم و یک قالب چایلد داریم که می توانیم آن را تقسیم کنیم. اما به همان تعداد سایت هایی جوملا که نیاز داریم، توزیع کنیم.
منابع فصل
مستندات رسمی جوملا یک مقاله جامع در مورد اظهارات jdoc دارد:
https://docs.joomla.org/Jdoc_statements
