فصل پنجم: استفاده از قدرت جوملا در کامپوننت شما

بیان خلاصه ای از بحث توسط هوش مصنوعی:

جوملا! یک سیستم مدیریت محتوای غنی از ویژگی ها است. با نصب تمیز جوملا، شما یک ابزار انتشار با ویژگی های عالی، از جمله موارد زیر دریافت کنید:

• تولید محتوا
• دسته بندی محتوا
• معماری محتوای خود را با فیلدهای سفارشی گسترش دهید
• داشتن یک سیستم چند زبانه خارج از محدودیت
• و بسیاری از ویژگی های دیگر

جوملا یک API برای ادغام برخی از ویژگی های اصلی آن در افزونه های شما ارائه می دهد. در این فصل، به بررسی این ویژگی ها خواهیم پرداخت و نحوه استفاده از آنها برای ایجاد افزونه های قدرتمندتر را یاد خواهیم گرفت. بیشتر این ویژگی ها مربوط به انتشار و ویرایش محتوای وب است، (مانند امکان سازماندهی محتوای ما به دسته ها.) اما برخی از آنها، مانند فیلدهای سفارشی، می توانند انعطاف پذیری زیادی را به افزونه ما ارائه دهند.

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

·         بررسی ویژگی های جوملا که می توانید در کامپوننت خود استفاده کنید

·         افزودن ACL به کامپوننت ما

·         بررسی مزایا و محدودیت  های استفاده از دسته  های جوملا

·         استفاده از دسته های جوملا در کامپوننت ما

·         مقدمه ای بر فیلدهای سفارشی جوملا

·         استفاده از فیلدهای سفارشی در کامپوننت ما

·         استفاده از قابلیت های چند زبانه جوملا در کامپوننت ما

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

الزامات فنی

در این فصل، ما به بهبود افزونه Simple Project Manager خود ادامه خواهیم داد، بنابراین شما به موارد زیر نیاز دارید :

• Visual Studio Code (یا ویرایشگر کد دلخواه شما)
• سایت جوملا که در فصل های قبل نصب کردیم

می توانید فایل های کد این فصل را در GitHub در اینجا پیدا کنید:

 https://github.com/PacktPublishing/Developing-Extensions-for-Joomla-5/tree/chapter05

بررسی ویژگی های جوملا که می توانید در کامپوننت خود استفاده کنید

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

برخی از این ویژگی ها را می توان در موارد استفاده ی چندگانه استفاده کرد، بنابراین توسعه دهندگان اصلی جوملا تصمیم گرفتند که ادغام آنها را با افزونه های دیگر آسان کنند. این زندگی ما را به عنوان توسعه دهندگان بسیار آسان تر می کند. از یک طرف، کد کمتری باید اضافه شود تا این رفتارهای پیچیده را به افزونه های اضافه کنیم. از طرف دیگر، لازم نیست نگران ادغام این ویژگی ها در کامپوننت خود با سایر بخش های اکوسیستم جوملا باشیم. بسیاری از توسعه دهندگان از ویژگی داده شده در افزونه های خود استفاده می کنند و ما می توانیم مطمئن باشیم که هیچ تضادی وجود نخواهد داشت.

ویژگی های زیر می توانیم در افزونه خود استفاده کنیم:

•  لیست کنترل دسترسی جوملا Joomla Access Control List ( ACL )  : یکی از بهترین و قویترین ویژگی های جوملا، سیستم مجوزهای ACL است. ACL به شما این امکان را می دهد که چندین گروه کاربری در یک سایت جوملا داشته باشید که هر کدام دارای مجوزها و قابلیت های متفاوتی هستند. برای کامپوننت ما، این یک راه عالی برای اعمال محدودیت  ها برای اقدامات خاص بر اساس گروه کاربری جوملا است.
• مدیریت دسته بندی جوملا  Joomla category management : سیستم دسته بندی جوملا بسیار قدرتمند است و به گونه ای طراحی شده است که هنگام مرتب سازی یا جستجوی داده ها عملکرد بالایی داشته باشد. طراحی آن از مدل محبوب مجموعه تودرتو پیروی می کند که در محیط های داده در حال رشد عالی عمل می کند.
• فیلدهای سفارشی جوملا Joomla custom fields : مدیران جوملا می توانند فیلدهای سفارشی خود را به مقالات اضافه کنند. این امکان استفاده انعطاف پذیر تر از جوملا را فراهم می کند، از جمله برای توسعه دایرکتوری ها، فروشگاه ها و سایر انواع وب سایت های عالی. می توانید با اجازه دادن فیلدهای سفارشی برای برخی از انواع داده های خود، از این انعطاف  پذیری در کامپوننت خود بهره ببرید.
• قابلیت های چند زبانه Multilingual capabilities : یکی از بزرگ  ترین ویژگی  هایی که با جوملا بیرون می  آید و هیچ سیستم مدیریت محتوای دیگری تاکنون موفق نشده است، قابلیت  های چند زبانه یک سایت جوملا است. هر مدیر وب می تواند یک سایت چند زبانه خارج از جعبه (اصطلاح Out of box یعنی پس از نصب قابل اجرا خواهد بود) ایجاد کند یا زبان  های مختلف را با چند کلیک به یک سایت موجود اضافه کند. و البته، ما می توانیم کامپوننت خود را با استفاده از API جوملا چند زبانه کنیم.
•  خدمات وب API Web Services : جوملا دارای یک API خدمات وب است تا بتوانیم وب سایت هایی فراتر از مرورگر وب ایجاد کنیم. با Web Services API جدید، می توانیم اکثر ویژگی های جوملا را با هر مشتری HTTP مدیریت کنیم. همانطور که در فصل بعدی خواهیم دید، می توانیم خدمات وب جوملا را برای تعامل با افزونه های خود گسترش دهیم.
• رابط خط فرمان Command-Line Interface : جوملا برای کارهایی که خارج از مرورگر بهتر انجام می شوند، یک رابط خط فرمان (CLI) ارائه می دهد. با CLI، می توانیم وظایف پردازش سنگین یا کارهایی را که باید به  طور خودکار با استفاده از یک CRON job یا یک کار برنامه  ریزی شده در سرورمان انجام شوند، انجام دهیم. نحوه ایجاد یک CLI برای برنامه افزودنی خود را در فصل 9 (افزودن یک CLI به کامپوننت خود) خواهیم دید.

ما همه این ویژگی ها را با استفاده از API جوملا یکپارچه خواهیم کرد، که ما را از ساختن آنها از ابتدا نجات می دهد. بیایید با اضافه کردن مجوزها به کامپوننت خود با جوملا ACL شروع کنیم.

افزودن ACL به کامپوننت ما

به عنوان توسعه دهندگان افزونه، ما از موقعیت هایی که مدیران وب در هنگام پیکربندی افزونه ها با آن مواجه می شوند، آگاه هستیم. به عنوان مثال، در افزونه  Simple Project Manager، ما نمی خواهیم نقش مشتری بتواند فاکتورها را ویرایش کند یا پروژه های ما را سازماندهی کند. همچنین نمی خواهیم کاربرانی که وارد سیستم نشده اند فاکتورهای ما را دانلود کنند.

ما باید برخی از مجوزها را تنظیم کنیم و اقداماتی را که یک کاربر می تواند در افزونه ی ما انجام دهد را مشخص کنیم. بنابراین، بیایید مثال خود را با ایجاد چند گروه کاربری اساسی در سایت جوملا برای تطبیق این مجوزها شروع کنیم.

راه اندازی گروه های کاربری جوملا و مشاهده سطوح دسترسی

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

ما قصد داریم موارد زیر را در گروه های کاربری سایت جوملا ایجاد کنیم و هدف هر گروه را بدانیم:

• مشتری Customer  : کاربران این گروه فقط می توانند مقدار بسیار محدودی از داده های پروژه مانند پیشرفت کارها، فاکتورها و چند مورد دیگر را ببینند.
• مدیر پروژه Project Manager  : این گروه فقط شامل چند کاربر خواهد بود و آنها می توانند تمام جنبه های پروژه را مدیریت کنند.
• حسابدار Accountant : یک گروه کوچکی که در آن کاربران فقط قادر به ایجاد و ویرایش فاکتورها خواهند بود.

برای انجام این اهداف، ما باید سطوح دسترسی مشاهده را برای گروه ها تنظیم کنید. بنابراین، به مدیر Users: Viewing Access Levels  می رویم و سطوح نمایش زیر را برای هر گروه اضافه می کنیم:

• مشتری : مشتری، مدیر پروژه، حسابدار، مدیر، کاربر فوق العاده

Customer: Customer, Project Manager, Accountant, Administrator, Super User

• مدیر پروژه : مدیر پروژه، مدیر، کاربر فوق العاده

Project Manager: Project Manager, Administrator, Super User

• حسابدار : مدیر پروژه، حسابدار، مدیر، کاربر فوق العاده

Accountant: Project Manager, Accountant, Administrator, Super User

 

این پیکربندی به ما سه گروه کاربری مختلف با دسترسی مختلف به منابع می دهد.

هنگامی که گروه های کاربری خود را راه اندازی کردیم، می توانیم پیکربندی مجوزها را به کامپوننت خود اضافه کنیم.

اضافه کردن پیکربندی مجوزها

به طور پیش فرض در جوملا، فقط کامپوننت ها اجازه می دهند تا برای اقدامات خاص مجوز داشته باشند. این امر به ما امکان می دهد تا در کنار استفاده از اقداماتی که قبلاً در جوملا آماده شده، اقدامات شخصی سازی شده نیز ایجاد کنیم.

برای ارائه تنظیمات مجوز برای کامپوننت خود، از فایل /src/component/admin/access.xml که در فصل 2 ایجاد کردیم، استفاده می کنیم. برای تکمیل، خط زیر را به ناحیه  sectionاضافه می کنیم:

 
<action name="core.edit.own" title="JACTION_EDIT_OWN"/> 

این خط یک مجموعه مجوز جدید به نام EDIT_OWN  اضافه می کند ، که ما از آن استفاده می کنیم تا کاربران بتوانند محتوایی را که ایجاد کرده اند، ویرایش کنند.

پس از اضافه کردن این خط، به محتوای فایل زیر می رسیم :

/src/component/admin/access.xml

 
<?xml version="1.0" encoding="utf-8"?> 
<access component="com_spm"> 
<section name="component"> 
<action name="core.admin" title="JACTION_ADMIN" /> 
<action name="core.options" title="JACTION_OPTIONS" /> 
<action name="core.manage" title="JACTION_MANAGE" /> 
<action name="core.create" title="JACTION_CREATE" /> 
<action name="core.delete" title="JACTION_DELETE" /> 
<action name="core.edit" title="JACTION_EDIT" /> 
<action name="core.edit.own" title="JACTION_EDIT_OWN" /> 
</section> 
</access> 

این اقدامات برای همه اکوسیستم های جوملا مشترک است. بیایید توضیح کوتاهی از این اقدامات را مرور کنیم:

• core.admin :  این به کاربران اجازه میدهد به ناحیه مدیریت افزونه دسترسی داشته باشند
• core.options :  این عمل مشخص می کند که آیا کاربر می تواند صفحه پیکربندی کامپوننت را ببیند یا خیر
• core.manage :  با این عمل، اجازه مدیریت داده های یک کامپوننت را می دهیم
• core.create :  وقتی کاربر مجاز به انجام این عمل باشد، می تواند آیتم های جدیدی در کامپوننت ایجاد کند
• core.delete :  این به کاربران اجازه می دهد تا داده ها را از کامپوننت حذف کنند
• core.edit :  این به کاربران اجازه می دهد تا هر موردی را در کامپوننت ویرایش کنند
• core.edit.own :  این اقدام به کاربر اجازه می دهد فقط موارد ایجاد شده توسط همان کاربر را ویرایش کند

هنگامی که اقدامات اصلی را به افزونه خود اضافه می کنیم، کامپوننت تنظیمات مجوز گروه کاربر را برای آن عملکرد به ارث می برد. بنابراین، اگر کاربر به گروه کاربران مشترک تعلق داشته باشد ، اجازه ایجاد یا ویرایش موارد را نخواهد داشت مگر اینکه مدیر وب این تنظیمات را در پیکربندی مجوزها تغییر دهد.

پس از افزودن فایل access.xml  به کامپوننت خود، به یاد داشته باشید که آن را نیز به فایل مانیفست اضافه کنید تا به درستی نصب شود. به فایل src/component/spm.xml  بروید و خط زیر را به زیر بخش file  در قسمت administration  اضافه کنید :

 
<file>access.xml</xml> 

هنگامی که محتوای access.xml را به کامپوننت خود اضافه کردیم ، باید مجوزها را به قسمت پیکربندی کامپوننت اضافه کنیم. بنابراین، فایل src/component/admin/config.xml  را ویرایش می کنیم و محتوای fieldset  زیر را به بخش config درست در زیر مجموعه فیلدهای  company_data قبلی که در فصل قبل ایجاد کرده ایم، اضافه می کنیم:

 

 
<fieldset name="permissions" label= 
"JCONFIG_PERMISSIONS_LABEL"> 
<field 
name="rules" 
type="rules" 
label="JCONFIG_PERMISSIONS_LABEL" 
filter="rules" 
validate="rules" 
component="com_spm" 
section="component" 
/> 
</fieldset> 

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

ما می توانیم پیکربندی مجوزها در صفحه گزینه  های کامپوننت بررسی کنیم (می توانید در این URL که در فصل قبل به تفصیل توضیح داده شد، پیدا کنید

http://yoursite.com/administrator/index.php?option=com_config&view=component&component=com_spm

 

احترام به مجوزهای موجود در افزونه ی ما

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

برای مشاهده مجوزها، اجازه دهید قبل از نمایش لیست فاکتورها بررسی کنیم که آیا کاربر مجاز است محتوای افزونه را مدیریت کند. برای این کار فایل src/component/admin/src/View/Invoices/HtmlView.php  را ویرایش کرده و کد زیر را به متد display اضافه کنید:

 
$user = Factory::getApplication()->getIdentity(); 
if (!$user->authorise('core.manage', 'com_spm')){ 
throw new GenericDataException('Not allowed', 403); 
} 

در این کد، کاربری را دریافت می کنیم که سعی می کند به لیست دسترسی پیدا کند و از متد authorise()  برای بررسی مجوز ویژه استفاده می کنیم. در این مثال، مجوز عمل core.manage  که برای کامپوننت com_spm  تعریف شده را بررسی می کنیم. اگر کاربر اجازه مدیریت افزونه را ندارد، جوملا یک اخطار ایجاد می کند و یک پیام مجاز نیست (Not allowed) به کاربر نشان می دهد.

نام عمل (action name) دقیقاً همان چیزی است که در فایل access.xml  از فصل قبل تعریف شده است، بنابراین می توانیم این بررسی مجوز را به هر بخشی از افزونه خود که نیاز داریم، اضافه کنیم.

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

تعریف اقدامات سفارشی برای کامپوننت ما

در افزونه خود، مناطق مختلف که دارای مجوز های متناقض هستند. به عنوان مثال، گروه کاربری حسابدار باید قادر به ایجاد فاکتور باشد، اما این گروه نباید وظایف ایجاد کنند. ما باید راهی برای تمایز این زمینه ها ارائه دهیم. اینجاست که اقدامات سفارشی به کمک ما می آیند.

بیایید با افزودن کد زیر به src/component/admin/access.xml خود، یک اقدام سفارشی برای تمایز بین این دو زمینه اضافه کنیم.

 
<action name="invoice.create" 
title="COM_SPM_ACTION_INVOICE_CREATE" /> 
<action name="invoice.edit" 
title="COM_SPM_ACTION_INVOICE_EDIT" /> 
<action name="task.create" 
title="COM_SPM_ACTION_TASK_CREATE" /> 

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

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

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

• کاربرانی که نمی توانند فاکتور ایجاد کنند، نباید دکمه New را ببینند یا به آدرسی برای ایجاد فاکتور دسترسی داشته باشند.
• اگر کاربر به نحوی موفق به ارسال یک درخواست معتبر برای ایجاد فاکتور شود، جوملا باید درخواست را رد کند.

در نماهای لیست کامپوننت SPM ، یک نوار ابزار خوب برای ایجاد موارد جدید اضافه کردیم. در لیست فاکتورها، این نوار ابزار را نیز نشان می دهیم و در واقع دکمه New  را برای ایجاد فاکتور اضافه کرده ایم.

بنابراین اکنون فایل src/component/admin/src/View/Invoices/HtmlView.php  را ویرایش می کنیم و آخرین خط متد addToolbar()  را با کد زیر جایگزین می کنیم:

 
$user = Factory::getApplication()->getIdentity(); 
if ($user->authorise('invoice.create', 'com_spm')){ 
$toolbar->addNew('invoice.add'); 
} 

این کد بررسی می کند که کاربر مجوزهای کافی برای ایجاد فاکتورها را داشته باشد و در این صورت دکمه New  را اضافه می کند. این سناریو را برای کاربرانی که نمی توانند فاکتورهای جدید ایجاد کنند (منظور مشتریان) را پوشش می دهد. برای رسیدگی به سناریوی دوم، باید به InvoiceController  رفته و بررسی لازم را در آنجا اضافه کنیم.

 ما فایل src/component/admin/src/Controller/InvoiceController.php  را ویرایش می کنیم و کد زیر را اضافه می کنیم :

 
protected function allowAdd($data = []) 
{ 
$user = $this->app->getIdentity(); 
return $user->authorise('core.create', $this->option) 
&& $user->authorise('invoice.create', $this-> 
option)); 
} 

این متد allowAdd()  را که در نمونه FormController  ، برای ایجاد InvoiceController  خود توسعه میدهیم، تعریف شده است. در این روش از همان متد authorise()  مانند پاراگراف های قبل استفاده می کنیم و نتایج را به صورت مقدار true/false بر می گردانیم. این متد قبل از ایجاد فاکتور جدید توسط کنترلر فراخوانی می شود، بنابراین نیازی به انجام کار دیگری نیست.

با این بررسی ساده، می توانیم مطمئن باشیم که مجوزها در افزونه ما رعایت می شوند و داده های ما امن نگه داشته خواهد شد.

استفاده از دسته بندی های جوملا در کامپوننت ما

در فصل 1، هنگامی که پایگاه داده را برای افزونه خود تعریف کردیم، یک ستون عدد صحیح به نام دسته بندی در جدول Projects اضافه کردیم. ما جدول پایگاه داده برای ذخیره دسته های خود ایجاد نکردیم، زیرا می خواهیم آن را با دسته بندی جوملا ادغام کنیم.

اکنون دسته بندی های خود را با استفاده از قدرت جوملا Joomla FrameworkTM ادغام می کنیم.

ابتدا فایل src/component/admin/forms/project.xml را ویرایش می کنیم تا فیلد زیر را اضافه کنیم:

 
<field 
name="category" 
type="category" 
extension="com_spm" 
default="" 
label="COM_SPM_PROJECT_FORM_CATEGORY_LABEL" 
description="COM_SPM_PROJECT_FORM_CATEGORY_DESCRIPTION" 
required="true" 
> 
<option value="">JOPTION_SELECT_CATEGORY</option> 
</field> 

در این کد، یک فیلد جدید از نوع category اضافه می کنیم. برای بیان نام افزونه خود از ویژگی  extension استفاده می کنیم.

این یک کادر انتخاب را در فرم ویرایش پروژه ی ما با تمام دسته  های مورد استفاده در زمینه افزونه نشان می دهد. در حال حاضر هیچ کدام وجود ندارد، اما می توانیم با مرورگر خود به yoursite.com/administrator/index.php?option=com_categories&extension=com_spm  ، یکی اضافه کنیم.

این رابط مدیر دسته  بندی معمولی است، اما افزودن پارامتر extension?com_spm باعث می شود فقط دسته  ها را در زمینه کامپوننت com_spm  در نظر بگیرد.

برای شفاف  تر کردن این موضوع برای کاربران افزونه، می توانیم منویی را در backend  برای دسترسی به این نما اضافه کنیم. بیایید به فایل src/component/spm.xml  خود برویم و کد پررنگ شده ی زیر را به بخش زیر منوی submenu بخش مدیر administrator  اصلی اضافه کنیم:

 
<menu link="option=com_spm&view=projects" img=" 
default"> 
COM_SPM_PROJECTS 
</menu> 
<menu link="option=com_categories&view= 
categories&extension=com_spm" img="default"> 
COM_SPM_PROJECT_CATEGORIES 
</menu> 
<menu link="option=com_spm&view=tasks" img="default"> 
COM_SPM_TASKS 
</menu> 

با این کد، ما دسترسی مستقیم به نمای لیست دسته بندی پروژه را برای کاربران فراهم می کنیم. در اولین دسترسی، یک لیست خالی از دسته ها و یک دکمه New را مشاهده می کنند که با آن می توانند دسته های جدید اضافه کنند. در بخش بعدی، می خواهیم ببینیم که چگونه می توانیم برخی از گزینه  های شخصی  سازی را برای دسته  های خود اضافه کنیم.

سفارشی کردن دسته بندی اجزای ما

استفاده از دسته ها جوملا، توسعه ما را به فیلدهای دسته بندی استاندارد محدود نمیکند. ما می توانیم ویژگی های سفارشی خود را با استفاده از فرم های جوملا به دسته های پروژه خود اضافه کنیم. بیایید یک ویژگی رنگ به دسته های پروژه خود اضافه کنیم. این به ما کمک می کند تا پروژه های خود را راحت تر تجسم کنیم.

برای افزودن ویژگی های بیشتر، یک فایل src/component/admin/forms/category.xml  با محتوای زیر ایجاد می کنیم:

 
<?xml version="1.0" encoding="utf-8"?> 
<form> 
<fields name="params"> 
<fieldset name="com_spm" label="COM_ 
SPM_CATEGORY_OPTIONS_FIELDSET" description=" 
COM_SPM_CATEGORY_OPTIONS_FIELDSET_DESCRIPTION"> 
<field name="color" type="color" default="" 
 label="COM_SPM_CATEGORY_OPTIONS_FIELD_COLOR"/> 
</fieldset> 
</fields> 
</form> 

این کد یک برگه جدید در نمای ویرایش دسته بندی با عنوان COM_SPM_CATEGORY_OPTIONS_FIELDSET  با کادر فراخوانی اطلاعات با متن COM_SPM_CATEGORY_OPTIONS_FIELDSET_DESCRIPTION  اضافه می کند که حاوی یک فیلد انتخاب رنگ است.

می توانید هر تعداد فیلد که نیاز دارید به این گروه  fieldset اضافه کنید ، به همراه هر تعداد فیلد مجموعه که برای افزونه خود لازم می دانید.

اکنون می توانیم از این گزینه رنگی جدید برای ایجاد لیست زیباتر در پروژه ها استفاده کنیم.

بررسی مزایا و محدودیت های استفاده از دسته بندی جوملا

هنگام ساخت سایت های بزرگ، باید به عملکرد توجه کنید و مطمئن شوید که سریع ترین و مطمئن ترین کد ممکن را ارائه می دهید. جوملا، از این امر مستثنی نیست و هر ویژگی، کد گذاری شده است تا بهترین راه حل ممکن برای رایج ترین یا بحرانی ترین سناریوها باشد.

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

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

مزایای اصلی استفاده از دسته بندی جوملا (به جای راه حل های خودمان)، به شرح زیر هستند:

• تمام منطق داخلی، قبلاً کد گذاری شده و به خوبی آزمایش شده است
• فهرست دسته بندی را با سفارشی سازی، فیلتر کردن و ویرایش  هایی که قبلاً انجام شده است، دریافت می کنید
• اجازه می دهد تا تعداد نامحدودی از دسته ها و زیر مجموعه ها داشته باشید
• می توانید آنها را با فیلدهای خود در پارامترها گسترش دهید
• می توانید از شمارنده  های اقلام دسته  بندی در backend  استفاده کنید

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

• اگر می خواهید آنها را اشکال زدایی کنید، آنها بر اساس یک الگوریتم پیچیده هستند (مجموعه تودرتو)
• اگر چه می توانید دسته  ها را برای افزودن برخی گزینه  ها شخصی  سازی کنید، این کار با افزودن پارامترها انجام می شود و ممکن است در برخی سناریوها کافی نباشد.
• دسته بندی های فهرست شده در backend  یک لیست دسته بندی عمومی با گزینه های کمی برای تغییر چیدمان و استایل خواهد بود.

البته، این وظیفه شما به عنوان توسعه دهنده است که تعیین کنید آیا مزایا از محدودیت های پروژه شما بیشتر است یا خیر. در Simple Project Manager  ما از دسته بندی جوملا برای دسته بندی پروژه ها استفاده می کنیم. در قسمت بعدی کدهای لازم برای ادغام دسته بندی جوملا به کامپوننت ما را اضافه می کنیم.

استفاده از ویژگی های سفارشی سازی دسته بندی ها

تا کنون، دسترسی مستقیم برای دیدن دسته بندی کامپوننت در backend  را ایجاد کرده ایم و یک فیلد اضافه کرده ایم تا پروژه هایمان را با یک دسته خاص در پایگاه داده مرتبط کنیم. اما باید به افزونه خود اطلاع دهیم که از دسته بندی جوملا و کد های مربوط به آن استفاده می کنیم.

بنابراین، ما باید خدمات مناسب را با متد boot به کامپوننت خود اضافه کنیم. برای انجام این کار ، فایلsrc/component/admin/services/provider.php  را ویرایش می کنیم. کد برجسته شده ی زیر را اضافه میکنیم:

 
use Joomla\CMS\Categories\CategoryFactoryInterface; 
use Joomla\CMS\Extension\Service\Provider\CategoryFactory; 
return new class implements ServiceProviderInterface 
{ 
public function register(Container $container){ 
$container->registerServiceProvider(new 
CategoryFactory('Piedpiper\Component\Spm')); 
$container->registerServiceProvider(new 
MVCFactory('\Piedpiper\Component\Spm')); 
$container->registerServiceProvider(new 
ComponentDispatcherFactory('\Piedpiper\ 
Component\Spm')); 
$container->registerServiceProvider(new 
RouterFactory('\Piedpiper\Component\Spm')); 
$container->set( 
ComponentInterface::class, 
function (Container $container) 
{ 
$component = new SpmComponent($container-> 
get(ComponentDispatcherFactoryInterface 
::class)); 
$component->setMVCFactory($container-> 
get(MVCFactoryInterface::class)); 
$component->setRouterFactory($container-> 
get(RouterFactoryInterface::class)); 
$component->setCategoryFactory($container-> 
get(CategoryFactoryInterface::class)); 
return $component; 
} 
); 
} 
}; 

در اولین خط برجسته شده، فضای نام را برای دسته های خود اعلام می کنیم و در دومی کلاس CategoryInterface  ارائه شده توسط جوملا را اضافه می کنیم. تا مدیریت دسته بندی آسان تر شود. سپس قابلیت هایCategoryFactory  را اضافه می کنیم.

همچنین باید فایل src/component/admin/src/Extension/SpmComponent.php  را ویرایش کنیم تا آبجکت CategoryServiceInterface را پیاده سازی کنیم، بنابراین این فایل اکنون به شکل زیر است:

 
... 
use Joomla\CMS\Categories\CategoryServiceTrait; 
use Joomla\CMS\Categories\CategoryServiceInterface; 
class SpmComponent extends MVCComponent implements 
CategoryServiceInterface, BootableExtensionInterface, 
RouterServiceInterface 
{ 
use RouterServiceTrait; 
use CategoryServiceTrait; 
... 
} 

در کد قبلی، کلاس های سرویس مورد استفاده خود را اعلام می کنیم و کلاس CategoryServiceInterface  را پیاده سازی می کنیم تا به طور خودکار سرویس دسته بندی را در boot کامپوننت خود فراخوانی کند.

پس از این، یک کار دیگر را باید انجام دهیم. ما باید category service را ایجاد کرده و جزئیات رابطه بین داده های ما و دسته ها را ارائه دهید. این سرویس عمدتاً برای استفاده در قسمت frontend سایت ما در نظر گرفته شده است، بنابراین جوملا، آن را در قسمت frontend کامپوننت ما جستجو خواهد کرد. ما فایل src/component/site/src/Service/Category.php  را با محتوای زیر اضافه می کنیم:

 
<?php 
namespace Piedpiper\Component\Spm\Site\Service 
defined('_JEXEC') or die; 
use Joomla\CMS\Categories\Categories; 
class Category extends Categories 
{ 
public function __construct($options) 
{ 
$options = array_merge($options, [ 
'extension' => 'com_spm', 
'table' => '#__projects', 
'field' => 'category', 
'key' => 'id', 
'statefield' => 'state', 
]); 
parent::__construct($options); 
} 
} 

در این کد، فقط باید این آرایه را با اطلاعات زیر در افزونه خود تعریف کنیم:

• نام افزونه ی ما
• جدولی که سرویس دسته بندی باید بررسی کند
• نام فیلد با شناسه دسته در جدول ما
• فیلدی که به عنوان کلید اصلی در جدول # __projects  استفاده می شود
• فیلدی در جدول ما که وضعیت را نشان می دهد

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

ما فایل src/component/admin/src/Model/ProjectsModel.php  را ویرایش می کنیم و دسته ها را با namespaces  اعلام کرده و متد getItems()  اضافه می کنیم:

 
use Joomla\CMS\Categories\Categories; 
use Joomla\CMS\Categories\CategoryNode; 
... 
public function getItems() 
{ 
$items = parent::getItems(); 
$categories = Categories::getInstance('spm'); 
foreach ($items as &$item) { 
$item->category = $categories->get($item-> 
category); 
$item->color = $item->category->getParams()-> 
get('color'); 
} 
return $items; 
} 

جوملا، متد getItems()  را فراخوانی می کند تا لیست آیتم ها را از پایگاه داده دریافت کند، بنابراین برای بررسی نتایج و اضافه کردن داده های دسته، یک override اضافه می کنیم.

در ویژگی category ، ما اطلاعات کامل دسته خود را داریم و می توانیم ویژگی color را ازparams  دریافت کنیم. این کد همچنین ویژگیcolor  را از دسته به آیتم کپی می کند تا دسترسی مستقیم بیشتری را فراهم کند.

در نهایت باید برای لیست آیتم ها به طرح قالب برویم و از ویژگی color استفاده کنیم. فایلsrc/component/admin/tmpl/projects/default.php  را ویرایش کنید و فیلد td  را با کد با زیر جایگزین کنید:

 
... 
<?php foreach ($this->items as $item) : ?> 
<tr> 
<td style="background-color: <?php echo $item-> 
color;?>"><?php echo $item->id; ?></td> 
<td style="background-color: <?php echo $item-> 
color;?>"><?php echo $item->name; ?></td> 
<td style="background-color: <?php echo $item-> 
color;?>"><?php echo $item->deadline; ?></td> 
</tr> 
<?php endforeach;?> 
... 

بالاخره داریم برای دسته بندی ها در پروژه از دسته های جوملا استفاده میکنیم. یک جنبه اساسی باقی مانده است که ما باید آن را پوشش دهیم تا یکپارچگی کامل داشته باشیم. در قسمت بعدی خواهیم دید که چگونه می توانیم قابلیت های ACL را به این دسته بندی ها اضافه کنیم.

افزودن ACL به دسته بندی کامپوننت ما

افزودن قابلیت های ACL به  دسته بندی افزونه با استفاده از جوملا  ACLآسان است. فقط باید بخش زیر را به فایل src/component/admin/access.xml خود اضافه کنیم:

 
<section name="category"> 
<action name="core.create" title="JACTION_CREATE" /> 
<action name="core.delete" title="JACTION_DELETE" /> 
<action name="core.edit" title="JACTION_EDIT" /> 
<action name="core.edit.state" title="JACTION_EDITSTATE" /> 
<action name="core.edit.own" title="JACTION_EDITOWN" /> 
</section> 

این قوانین ACL فقط برای دسته  هایی در زمینه افزونه ما اعمال میشود، بنابراین می توانیم یک گروه کاربری مجاز به ایجاد دسته  بندی محتوا داشته باشیم، اما مجاز به افزودن دسته  ها به پروژه هایمان نیستیم.

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

مقدمه ای بر فیلدهای سفارشی جوملا

فیلدهای سفارشی جوملا یکی از هیجان انگیزترین ویژگی های اضافه شده به جوملا 3 بود.

این ویژگی به شما امکان می دهد فیلدهای بیشتری را به هر نهاد داده در جوملا اضافه کنید. رایج ترین مورد استفاده در اینجا اضافه کردن فیلدهای بیشتر به مقاله جوملا است، اما این ویژگی به مقالات جوملا محدود نمی شود. در واقع، می توانید فیلدهای سفارشی برای کامپوننت  هایی مانند  com_users (مسئول مدیریت کاربران جوملا) و (com_contact  افزودن یک فهرست تماس به سایت خود) پیدا کنید.

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

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

بیایید ببینیم که در بخش بعد چگونه فیلدهای سفارشی را به افزونه ی خود اضافه می کنیم.

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

ما می توانیم قابلیت های فیلد سفارشی را به هر بخشی از افزونه خود اضافه کنیم. بنابراین خوب است که از قبل تصمیم گیری در مورد مکان آن، بررسی کنیم کجای افزونه ی ما برای این فیلد ها منطقی است.

در افزونه Simple Project Manager، ما چندین نهاد داشتیم: پروژه هاProjects  ، مشتریان Clients ، فاکتورها Invoices و وظایف Tasks . هر کسب و کاری متفاوت است و نیازهای متفاوتی دارد. برای توسعه ما، من امکانات بسیار خوبی برای پیاده سازی فیلدهای سفارشی برای مشتریان و فاکتورها می بینم.

در جوملا، فیلدهای سفارشی را بر اساس زمینه (context) تعریف می کنیم. این بدان معناست که فیلدهای ایجاد شده در زمینه مشتری با آنهایی که در زمینه فاکتورها ایجاد شده اند یا مرتبط هستند، نشان داده نمی شوند.

بیایید پیاده سازی فیلدهای سفارشی را در کامپوننت خود با تعریف زمینه هایی که فیلد ها را به آنها اضافه خواهیم کرد، شروع کنیم. برای تعریف زمینه برای فیلدهای سفارشی خود، فایل src/component/admin/src/Extension/SpmComponent.php  را ویرایش کنید و فضای نام زیر را اضافه کنید:

 
use Joomla\CMS\Fields\FieldsServiceInterface; 
use Joomla\CMS\Factory; 
use Joomla\CMS\Language\Text; 

ما همچنین تعریف کلاس را به این شکل تغییر می دهیم:

 
class SpmComponent extends MVCComponent implements 
CategoryServiceInterface, BootableExtensionInterface, 
RouterServiceInterface, FieldsServiceInterface 

در کد قبلی،  FieldsServiceInterface را معرفی کردیم تا امکان تعریف فیلدهای سفارشی فراهم شود. در نهایت متدهای زیر را اضافه می کنیم:

 
public function getContexts(): array 
{ 
Factory::getLanguage()->load('com_spm', JPATH_ADMINISTRATOR); 
$contexts = array( 
'com_spm.project' => Text::_ 
('COM_SPM_CONTEXT_PROJECTS'), 
'com_spm.client' => Text::_ 
('COM_SPM_CONTEXT_CLIENTS') 
); 
return $contexts; 
} 
public function validateSection($section, $item = null) 
{ 
if (($section === 'customer')) { 
$section = 'client'; 
} 
if (($section === 'project')) { 
$section = 'project'; 
} 
if ($section !== 'project' && $section !== 'client') { 
return null; 
} 
return $section; 
} 

متد getContexts () ، توسط مدیر فیلدهای سفارشی جوملا فراخوانی خواهد شد تا زمینه های متفاوت را هنگام افزودن فیلدهای سفارشی به افزونه ما ارائه دهد. برای اینکه ببینیم چگونه کار می کند، باید به نمای مدیریت فیلدهای سفارشی برای پروژه های خود برویم. برای انجام این کار، به این URL در سایت جوملا  خود بروید:

yoursite.com/administrator/index.php?option=com_fields&context=com_spm.project

متد validateSection() بررسی روابط مورد نیاز را به عهده دارد و بخش مناسب را با توجه به زمینه کاربر بر می گرداند. این زمانی مفید است که از نام  های مختلف برای زمینه  های فیلد و نماها خود استفاده می کنیم. در این مورد، ما زمینه فیلد clients  را تعریف کردیم، اما در نمای مشتریان هستیم ، بنابراین بخش را در متد validateSection()  می  گیریم و رفع می کنیم.

و با آن، کار شما تمام شده است! اکنون می توانید از این نما، فیلدهای سفارشی را به پروژه های خود اضافه کنید. همچنین در بالای سمت راست ناحیه کامپوننت، کادر انتخابی را مشاهده خواهید کرد که با استفاده از آن می توانید به زمینه Client تغییر دهید.

برای آسان تر کردن کارها برای کاربرانمان، می توانیم لینکی را در منوی افزونه ی جوملا اضافه کنیم. برای انجام این کار، کد برجسته شده زیر را به فایل مانیفست در src/component/spm.xml اضافه کنید:

 
<submenu> 
<menu link="option=com_spm&view=projects" 
img="default"> 
COM_SPM_PROJECTS 
</menu> 
<menu link="option=com_fields&context= 
com_spm.project" img="default"> 
JGLOBAL_FIELDS 
</menu> 
<menu link="option=com_fields&view=groups& 
context=com_spm.project" img="default"> 
JGLOBAL_FIELD_GROUPS 
</menu> 
</submenu> 

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

نمایش فیلدهای سفارشی در نماهای ما

کار شما در اینجا به عنوان یک توسعه دهنده، شامل راه اندازی و تنظیم استفاده از فیلدهای سفارشی است، اما پس از انجام، کنترلی بر نحوه استفاده کاربران از این ویژگی ندارید. بنابراین، برای نشان دادن نحوه نمایش فیلدهای سفارشی در فرم  ها و چیدمان  ها، بیایید یک مورد ساده استفاده از فیلدهای سفارشی را در افزونه Simple Project Manager تصور کنیم.

بیا وانمود کنیم شما (که به عنوان کاربر عمل می کنید) می خواهید یک عملکرد ساده مدیر ارتباط با مشتری ( CRM ) داشته باشید. برای ایجاد آن، به نمای گروه های فیلد سفارشی برای زمینه مشتری رفته و گروه فیلد سفارشی CRM  را ایجاد می کنید.

سپس، به مدیر فیلد سفارشی برای زمینه Client بروید و فیلدهای زیر را اضافه کنید:

• تولد Birthday: یک فیلد تقویم
• وضعیت تأهل Married to: یک فیلد متنی
• تعداد فرزند Children: یک فیلد عدد صحیح

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

ممکن است فکر کنید که اکنون باید چیزی به مدل خود اضافه کنیم تا این فیلدها و محتوای آنها را نشان دهیم. اما از آنجایی که ما از روش های جوملا پیروی می کنیم، نیازی به انجام کاری نیست. داده های فیلدهای سفارشی به صورت جادویی توسط افزونه سیستم فیلدهای سفارشی بارگذاری می شوند. تنها کاری که باید انجام دهیم این است که کدی را برای نمایش فیلدهای سفارشی در view اضافه کنیم. بنابراین، اجازه دهید فایل src/component/admin/tmpl/customer/edit.php  و کد زیر را اضافه کنید:

 
<fieldset name="custom_fields"> 
<div class="row"> 
<div class="col-md-9"> 
<div class="row"> 
<div class="col-md-6"> 
<?php foreach($this->form-> 
getFieldsets() as $name => $fieldset): ?> 
<?php foreach($this->form-> 
 getFieldSet($name) as $field 
) :?> 
<?php echo $field-> 
renderField(); ?> 
<?php endforeach;?> 
<?php endforeach; ?> 
</div> 
</div> 
</div> 
</div> 
</fieldset> 

با این کار، ما نشانه گذاری را برای مجموعه فیلدهای HTML جدید اضافه میکنیم، و آن را با یک حلقه foreach  پر کنید که مجموعه فیلدها را از آبجکت  Form دریافت می کند ( $this->form ). در نهایت، فیلد را با استفاده از renderField()  ارائه شده توسط آبجکت Field  رندر می کنیم.

برای نمایش فیلدهای سفارشی در نمای frontend، از پلاگین سیستم فیلدهای سفارشی (custom fields system) نیز بهره می بریم. برای انجام این کار، قبل از فراخوانی متد والد، کد زیر را به فایل src/component/site/src/ViewCustomer در داخل متد display()  اضافه می کنیم:

 
$app = \Joomla\CMS\Factory::getApplication(); 
$app->triggerEvent('onContentPrepare', ['com_spm.customer', 
&$this->item]) 

;

این خط، متد مناسب افزونه سیستم فیلدهای سفارشی را فراخوانی کرده و زمینه مناسب را برای دریافت تمام فیلدهای سفارشی متصل به افزونه ی ما فراهم می کند. اکنون، در چیدمان قالب خود، می توانیم به تمام فیلدهای سفارشی داخل ویژگی jcfields آبجکت item دسترسی داشته باشیم.

برای انجام این کار، فایل  src/component/site/tmpl/customer/default.php  را با بلوک کد زیر اضافه کنید:

 
<div id="crm"> 
<?php foreach ($this->item->jcfields as $field) :?> 
<dl> 
<dt> 
<?php echo $field->label; ?> 
</dt> 
<dd> 
<?php echo $field->value; ?> 
</dd> 
</dl> 
<?php endforeach; ?> 
</div> 

با این حلقه foreach ، تمام فیلدهای مختلف متصل به item خود را مرور می کنیم. جالب  تر این که ویژگی $field  حاوی تمام ویژگی های فیلد است. این به ما امکان می دهد برچسب را از فیلد با استفاده از ویژگی $field->label  نشان دهیم. همچنین، اگر از یک فیلد پیچیده استفاده کنیم که قبل از نشان دادن مقدار، نیاز به پیش پردازش دارد، ویژگی value  مقدار مورد انتظار را خواهد داشت. به عنوان مثال، هنگام استفاده از یک فیلد select، ویژگی value ، متن مرتبط با انتخاب شده را ارائه می دهد. اگر می خواهید مقدار دقیق ذخیره شده در پایگاه داده خود را بدست آورید، از ویژگی rawvalue استفاده کنید.

افزودن ACL به فیلدهای سفارشی

افزودن قابلیت  های ACL به دسته  های برنامه افزودنی با استفاده از جوملا ACL آسان است. فقط باید بخش زیر را به فایل src/component/admin/access.xml خود اضافه کنیم:

 
<section name="fieldgroup"> 
 <action name="core.create" title="JACTION_CREATE" 
description="COM_FIELDS_GROUP_PERMISSION_CREATE_DESC" /> 
 <action name="core.delete" title="JACTION_DELETE" 
description="COM_FIELDS_GROUP_PERMISSION_DELETE_DESC" /> 
 <action name="core.edit" title="JACTION_EDIT" 
description="COM_FIELDS_GROUP_PERMISSION_EDIT_DESC" /> 
 <action name="core.edit.state" title= 
"JACTION_EDITSTATE" description=" 
 COM_FIELDS_GROUP_PERMISSION_EDITSTATE_DESC" /> 
 <action name="core.edit.own" title="JACTION_EDITOWN" 
description="COM_FIELDS_GROUP_PERMISSION_EDITOWN 
_DESC" /> 
 <action name="core.edit.value" title=" 
 JACTION_EDITVALUE" description=" 
COM_FIELDS_GROUP_PERMISSION_EDITVALUE_DESC" /> 
</section> 
<section name="field"> 
 <action name="core.delete" title="JACTION_DELETE" 
description="COM_FIELDS_FIELD_PERMISSION_DELETE_DESC" 
/> 
 <action name="core.edit" title="JACTION_EDIT" 
description="COM_FIELDS_FIELD_PERMISSION_EDIT_DESC" 
/> 
 <action name="core.edit.state" title= 
"JACTION_EDITSTATE" description=" 
 COM_FIELDS_FIELD_PERMISSION_EDITSTATE_DESC" /> 
 <action name="core.edit.value" title= 
"JACTION_EDITVALUE" description= 
 "COM_FIELDS_FIELD_PERMISSION_EDITVALUE_DESC" /> 
</section> 

در کد XML قبلی می توانیم دو گروه اصلی را ببینیم که در بخش های fieldgroup و field قرار دارند. گروه مجوزهایACL، فیلد fieldgroup را برای ویژگی گروه فیلدها تنظیم می کند. این به کاربر اجازه می دهد تا تعیین کند که افراد می توانند با فیلدهایی که به گروه تعلق دارند، کاری انجام دهند. این تنظیمات به شرح زیر است:

•  core.create : اجازه ایجاد فیلدهای جدید در داخل گروه را می دهد.
• core.delete :  حذف فیلدهایی را که به گروه تعلق دارند اجازه می دهد.
•  core.edit : به کاربران شما اجازه می دهد تا فیلدهای متعلق به این گروه را ویرایش کنند.
•  core.edit.state : به کاربر اجازه می دهد تا وضعیت فیلدهای داخل گروه را تغییر دهد.
• core.edit.own :  به کاربر اجازه می دهد تا فیلدهایی را که به گروه فیلد تعلق دارند و توسط همان کاربر ایجاد شده اند را ویرایش کند.
•  core.edit.value : تعیین می کند که کدام گروه کاربری می توانند مقدار یک فیلد را در این گروه فیلدها تغییر دهند.

بخش فیلد ACL​ را برای تمام فیلد های سفارشی افزونه تنظیم می کند. این برای مدیر وب سایت برای تنظیم مجوزهای عمومی برای فیلدها به جای استفاده از مجوزهای گروه فیلد مفید است. این تنظیمات موجود هستند:

• core.edit :  به ما امکان می دهد تعریف فیلد سفارشی را ویرایش کنیم
•  core.edit.state : به ما امکان می دهد وضعیت فیلد سفارشی را تنظیم کنیم
•  core.edit.value : به ما امکان می دهد تعیین کنیم کدام گروه های کاربری می توانند مقدار یک فیلد را در این گروه فیلد تغییر دهند.

توجه داشته باشید:

مجوز state همچنین به کاربر اجازه می دهد یک فیلد را به سطل زباله منتقل کند. بنابراین این مجوز می تواند گزینه  remove items در نظر گرفته شود. هنگام استفاده از این مجوزها، موارد این گونه را در نظر داشته باشید.

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

استفاده از قابلیت های چند زبانه جوملا در کامپوننت ما

در حال توسعه کامپوننت ما، ممکن است متوجه شده باشید که ما هرگز از زبان طبیعی برای برچسب ها و متون خود استفاده نکردیم. در عوض، از رشته  های کلیدی با نحو COM_SPM_CONTEXT_DETAIL  استفاده کردیم. این برای استفاده از سیستم ترجمه جوملا است که به ما امکان می دهد افزونه خود را به چندین زبان ارائه دهیم.

سیستم ترجمه جوملا بسیار قدرتمند است، اما همچنان بسیار ساده است. این بر اساس فایل های متنی ذخیره شده با پسوند ini است. این فایل هایini  حاوی فهرستی از رشته  های کلیدی برای ترجمه هستند که با علامت تساوی و ترجمه احاطه شده با نقل قول همراه است. هنگام بارگذاری صفحه، جوملا، این فایل هایini  را می  خواند و از آنها برای ترجمه تمام کلمات ارسال شده از کلاس  Text  استفاده می کند. سادگی سیستم این امکان را فراهم می کند که ترجمه ها را به راحتی لغو کنید و حتی ممکن است یک ترجمه اصلی را فقط با ایجاد رشته کلید همان زبان لغو کنید. به همین دلیل است که ما معمولاً رشته های کلید خود را با نام پیشوند کامپوننت می کنیم : COM_SPM.

بیایید اولین ترجمه خود را با ایجاد یک فایل src/component/admin/language/en-GB/com_spm.ini شروع کنیم، با محتوای زیر:

 
; General 
COM_SMP_NAME="Simple Project Manager" 

در خط اول، ما یک Comment (نظر) اضافه کردیم تا مشخص کنیم رشته، مربوط به کدام بخش از افزونه ی ما است. این ضروری نیست و تنها ابزاری برای کمک به مترجمان احتمالی آینده است تا زمینه رشته زبان را تشخیص دهند.

در قسمت ترجمه هر بخش می توانیم از فاصله ها و هر کاراکتر دیگری که نیاز داریم، استفاده کنیم. تنها یک هشدار وجود دارد: اگر از کاراکتر " double-quotes" در متن ترجمه خود استفاده کردیم، باید از علامت \  استفاده کنیم. بنابراین، به عنوان مثال، می توانیم کلمه Project  را با استفاده از \ علامت گذاری کنیم:

 
; General 
COM_SPM_NAME="Simple \"Project\" Manager" 

یکی از سناریوهای رایج نیاز به گنجاندن کد HTML در رشته های زبان برای غنی سازی متن است. نیازی به علامت های اضافی، پوشش یا ملاحظات دیگر نیست. همانطور که در مثال زیر مشاهده می شود :

 
COM_SPM_DESCRIPTION="Simple Project manager is an example 
component for the \"Developing Joomla Extensions\" book 
published by <a href='https://packt.com'>Packt</a>" 

این رشته ترجمه شامل یک پیوند است. برای سهولت در خواندن، از single quotes ' ' برای ویژگی های HTML استفاده می کنیم.

برای شناسایی و ترجمه رشته های کلید، جوملا از کلاس \Joomla\CMS\Language\Text  استفاده می کند. هیچ چیز دیگری در فایل های XML مانند فایل مانیفست یا فایل های تعریف فرم وجود ندارد. جوملا تمام رشته های کلیدی ممکن را به کلاس  Text ارسال می کند و نتیجه را نشان می دهد.

بنابراین، اگر به مانیفست افزونه واقع در src/component/spm.xml برگردیم ، ورودی  های زیر را پیدا می کنیم :

 
... 
<name>COM_SPM</name> 
... 
<description><![CDATA[COM_SPM_DESCRIPTION]]></description> 
... 

فقط چند رشته کلید در این فایل مانیفست وجود دارد. یکی نام افزونه (COM_SPM_NAME) و دیگری توضیحات (COM_SPM_DESCRIPTION). پس از نصب افزونه، جوملا این رشته ها را در پیام موفقیت نشان می دهد. اما جوملا فقط فایل های .ini مربوط به زمینه را بارگیری می کند. به عنوان مثال، وقتی افزونه ی خود را نصب می کنیم، در زمینه com_installer هستیم نه در زمینه com_spm، به این معنی که جوملا رشته های کلید ما را ترجمه نمی کند.

برای رفع این مشکل، باید یک فایل زبان جدید در همان پوشه به نام com_spm.sys.ini ایجاد کنیم. جوملا همیشه همه فایل های زبان sys.ini موجود در سیستم را بدون توجه به زمینه بارگیری می کند. ما از این فایل برای افزودن ترجمه برای مواردی که در زمینه های دیگر مانند نصب و منوها اتفاق می افتد، استفاده می کنیم.

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

 
; General 
COM_SMP_NAME="Simple Project Manager" 
COM_SPM_DESCRIPTION="Simple Project manager is an example 
component for the \"Developing Joomla Extensions\" book 
published by <a href='https://packt.com'>Packt</a>" 

هنگام استفاده از کلیدهای ترجمه یکسان در هر دو فایل هیچ تضادی وجود ندارد زیرا سیستم زبان جوملا همه رشته ها را در حافظه بارگذاری می کند و اولین تطابق ترجمه شده را نشان خواهد داد.

همه چیزهایی که تاکنون دیده  ایم شامل اضافه کردن یک نقشه ترجمه برای زبان انگلیسی است، نقشه  ای که به طور پیش  فرض در جوملا استفاده می شود. اگر می خواهیم زبان  های دیگری را هم اضافه کنیم، باید یک پوشه متفاوت ایجاد کنیم و فایل های sys.ini و ini  مربوطه را ایجاد کنیم. به عنوان مثال، اگر بخواهیم پشتیبانی از زبان آلمانی را اضافه کنیم، می توانیم فایل ها را در پوشه src/component/admin/language/de-DE/  کپی کنیم تا فایل های زیر را داشته باشیم:

• src/component/admin/language/de-DE/com_spm.ini
• src/component/admin/language/de-DE/com_spm.sys.ini

هنگام کار با محتوای PHP، ما همچنان از کلاس Text  استفاده می کنیم. اگر فایل src/component/admin/tmpl/projects/default.php  را مشاهده کنیم، اعلان کلاس Text  را در بالای فایل به صورت زیر مشاهده خواهیم کرد:

 
use Joomla\CMS\Language\Text; 

همچنین استفاده از کلاس را با متد زیر مشاهده می کنیم:

 
Text::_('COM_SPM_PROJECTS_LIST') 

این باعث می شود جوملا در فایل com_spm.ini  رشته کلید COM_SPM_PROJECTS_LIST  را جستوجو کرده و مقدار اعلام شده ی آن را برگرداند.

اکنون که می دانیم چگونه ترجمه  های خود را اضافه کنیم، می توانیم کمی عمیق  تر برویم و چند ویژگی از کلاس Text  را ببینید تا ترجمه های بی نقصی تولید کنید.

اضافه کردن ترجمه های پیچیده

جوملا تاکنون بیش از 50 بسته زبان رسمی در دسترس دارد و با کشف قدرت آن توسط کاربران در سراسر جهان، زبان های بیشتری در راه است. در همه این زبان ها موارد و روش های جالبی برای بیان یک مفهوم پیدا می کنیم. بیایید جمله زیر را مثال بزنیم:

20 items deleted.

این جمله ما را از تعداد موارد حذف شده مطلع می کند. آیا باید برای هر شماره ممکن یک پیام متفاوت ایجاد کنیم؟ البته که نه! جوملا به ما اجازه می دهد تا از متغیرها برای مدیریت این موقعیت ها استفاده کنیم. این روش ها به شرح زیر است:

 
Text::sprintf() 
Text::plural() 

متد Text ::sprintf() رشته را با تعدادی متغیرهایی می گیرد که با متغیرهایی که رشته را دنبال می کنند، جایگزین می شوند. به عنوان مثال، در پروژه ی ما، اجازه دهید از Key-value زیر در فایل com_spm.ini  استفاده کنیم:

 
COM_SPM_REMOVED_ITEMS="%d items deleted" 

و در کد PHP خود از خط زیر استفاده خواهیم کرد:

 
echo Text::sprintf('COM_SPM_REMOVED_ITEMS', ["20"]); 

یک چیز جالب در مورد متد Text::sprintf()  این است که دقیقاً مانند تابع sprintf() در PHP  کار می کند ، بنابراین همان متغیرها را می پذیرد و دقیقاً مانند قبلی رفتار می کند. با این حال، به موارد زیر توجه کنید:

• می توانید نوع داده  ای را که انتظار دارید، تنظیم کنید (به عنوان مثال، %d  برای مقادیر صحیح است).
• ترتیب جایگزینی به ترتیب متغیرهای آرایه ای که بعد از رشته ارائه می کنیم، احترام می گذارد.
• می توانید با استفاده از شماره موقعیت آن در پوزیشن مکان خود، متغیر خاصی را جایگزین کنید. به عنوان مثال، اگر %2$d  را اضافه کنید، این متد از دومین متغیر ارسال شده در آرایه برای جایگزینی آن مکان استفاده می کند، مهم نیست در کجای رشته ظاهر شود.

متد Text ::plural() برای ارائه ترجمه های مختلف برای زمانی که تعداد آیتم ها تغییر می کند، استفاده می شود. به عنوان مثال، در زبان انگلیسی، زمانی که یک آیتم در مقابل چندین آیتم داریم، عبارت یکسان نیست. در مثال ما، می توانیم کد خود را به صورت زیر بازنویسی کنیم:

 
echo Text::plural('COM_SPM_REMOVED_ITEMS', 20); 

و سپس اگر رشته زیر را به فایل com_spm.ini اضافه کنیم ، زمانی که یک آیتم داشته باشیم، از رشته مقدار زیر استفاده می شود:

 
COM_SPM_REMOVED_ITEMS_1="Item successfully removed" 

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

اکنون ما آماده ایم کامپوننت خود را ترجمه کرده و درک آنچه را که می خواهیم بگوییم را برای کاربرانمان آسان تر کنیم، صرف نظر از زبانی که صحبت می کنند.

منابع فصل

• شما می توانید یک آموزش عالی در مورد ACL های جوملا در مستندات رسمی جوملا پیدا کنید:

 https://docs.joomla.org/J3.x:Access_Control_List_Tutorial

• در مستندات رسمی جوملا، یک مقاله ی مفصل با همه ی چیزهایی که باید هنگام ترجمه افزونه خود بدانید وجود دارد :

 https://docs.joomla.org/International_Enhancements_for_Version_1.6#Pluralization_Support_for_Translation_Files

• فرمت فایل ini  جوملا در اسناد رسمی زیر توضیح داده شده است :

 https://docs.joomla.org/Creating_a_language_definition_file

• صفحه استانداردهای کدنویسی جوملا دستورالعمل هایی را برای فایل های ini ارائه می دهد:

  https://developer.joomla.org/coding-standards/ini.html