فیلدهای فرم

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

می‌توانید این کامپوننت نمونه را دانلود کنید که تعدادی از جنبه‌های شرح داده شده در اینجا را نمایش می‌دهد.

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

مقدمه

جوملا طیف گسترده‌ای از انواع فیلدها را در اختیار شما قرار می‌دهد که می‌توانید در فرم‌های خود استفاده کنید. کد منبع این نوع فیلدها در مسیر libraries/src/Form/Field قرار دارد و در این بخش از راهنمای جوملا توضیح داده شده‌اند.

برای امتحان یک فیلد استاندارد فرم، می‌توانید کامپوننت com_exampleform را از کامپوننت Exampleform دانلود کرده و فایل /site/forms/example_form.xml را ویرایش کنید تا فیلدی که می‌خواهید بررسی کنید را اضافه نمایید.

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

در ادامه فهرست کامل تمامی فیلدهای فرم ارائه شده در این نسخه آمده است.

نوع فیلد	توضیحات
Accessible Media	دسترسی مدال به مدیریت رسانه برای درج تصاویر همراه با امکان بارگذاری برای کاربران دارای مجوز و فیلد متنی برای افزودن متن جایگزین.
Access Level	ارائه لیست کشویی از سطوح دسترسی مشاهده.
Alias Tag	ارائه لیست باکس شامل تعاریف زبان خاص.
Author	ارائه لیست باکسی شامل نویسندگان (کاربران) که محتوا ایجاد کرده‌اند.
Cache Handler	ارائه لیستی از گزینه‌های مدیریت کش موجود.
Calendar	یک جعبه متنی برای وارد کردن تاریخ. یک نماد کنار جعبه متن لینک به تقویم پاپ‌آپ را فراهم می‌کند.
Captcha	استفاده از افزونه کپچا را فراهم می‌کند.
Category	ارائه لیست کشویی از دسته‌بندی‌های یک افزونه.
Checkbox	یک چک‌باکس برای انتخاب یا عدم انتخاب.
Checkboxes	تعداد نامحدود چک‌باکس برای انتخاب چندگانه.
Chrome Style	ارائه لیستی از گزینه‌های سبک کروم قالب، گروه‌بندی شده بر اساس قالب.
Color	انتخابگر رنگ هنگام کلیک روی جعبه ورودی.
Combo	ارائه فیلد جعبه ترکیبی (کامبو).
Component Layout	لیست گروه‌بندی شده از چیدمان‌های جایگزین هسته و قالب برای آیتم‌های یک کامپوننت.
Components	لیست باکس شامل افزونه‌های فعال از نوع کامپوننت.
Content History	پاپ‌آپ مدالی که تاریخچه ویرایش یک مقاله را نشان می‌دهد.
Content Language	ارائه لیستی از زبان‌های محتوا.
Content Type	ارائه لیستی از نوع محتوا.
Database Connection	ارائه لیستی از اتصال‌های موجود به پایگاه داده، با امکان محدودسازی به یک لیست خاص.
Editor	فراهم کردن یک بخش ویرایشگر.
Email	فیلدی برای وارد کردن ایمیل.
File	فیلد ورودی فایل.
File List	لیست کشویی از فایل‌های یک دایرکتوری مشخص.
Folder List	لیست کشویی از پوشه‌های یک دایرکتوری مشخص.
Frontend Language	ارائه لیستی از زبان‌های محتوا منتشر شده با صفحات اصلی.
Grouped List	لیست کشویی از آیتم‌ها دسته‌بندی شده در گروه‌ها.
Header Tag	لیست کشویی از تگ‌های سرلیک (h1 تا h6).
Hidden	فیلد مخفی برای ذخیره مقدار فرم که کاربر در مدیریت نمی‌تواند مستقیماً تغییر دهد.
Image List	لیست کشویی از فایل‌های تصویر در یک دایرکتوری مشخص.
Integer	لیست کشویی از اعداد صحیح بین حداقل و حداکثر.
Language	فهرست کشویی زبان‌های نصب شده برای بخش فرانت‌اند یا بک‌اند.
Last Visit Date Range	لیست باکسی از بازه‌های زمانی جهت فیلتر تاریخ آخرین بازدید.
Limit Box	لیستی از محدودیت تعداد آیتم‌ها.
List	لیست کشویی از ورودی‌های تعریف شده توسط کاربر.
Media	دسترسی مدال به مدیریت رسانه برای درج تصاویر با امکان بارگذاری برای کاربران مجاز.
Menu	لیست کشویی از منوهای موجود در سایت جوملا شما.
Menu Item	لیست کشویی از آیتم‌های منو موجود در سایت جوملا شما.
Meter	نمایش نوار اندازه‌گیری برای نشان دادن مقدار در یک بازه.
ModalSelect	فیلدی برای انتخاب آیتم داخل یک پنجره مدال.
Module Layout	لیست جایگزین برای چیدمان ماژول‌ها، گروه‌بندی شده بر اساس هسته و قالب.
Module Order	لیست کشویی برای تنظیم ترتیب ماژول‌ها در یک موقعیت مشخص.
Module Position	فیلد متنی برای تعیین موقعیت ماژول.
Module Tag	لیستی از عناصر html5 (برای پوشش دادن ماژول).
Note	فیلد متنی یک خطی.
Number	جعبه متنی یک خطی با دکمه‌های بالا و پایین برای تنظیم عدد.
Order	لیست کشویی از ورودی‌ها در یک جدول مشخص به همراه گزینه‌های «اولین» و «آخرین».
Password	جعبه متنی برای وارد کردن رمز عبور که حروف را مخفی می‌کند.
Plugins	لیستی از پلاگین‌ها در یک پوشه مشخص.
Plugin Status	لیست باکس وضعیت‌ها.
Predefined List	لیستی از مقادیر پیش‌تعریف شده.
Radio Basic	دکمه‌های رادیویی با سبک پیش‌فرض (در آینده حذف می‌شود).
Radio	دکمه‌های رادیویی برای انتخاب گزینه‌ها.
Range	اسکرول بار افقی برای تعیین مقدار در یک بازه.
Redirect Status	لیست باکس وضعیت‌های تغییر مسیر.
Registration Date Range	لیست باکس بازه‌های زمانی ثبت نام.
Rules	ماتریس گزینه‌های گروه‌بندی شده برای مدیریت کنترل دسترسی. نمایش بر اساس زمینه متفاوت است.
Schema Org Component Sections	لیست باکس شامل افزونه‌های فعال از نوع کامپوننت.
Session Handler	لیست کشویی گزینه‌های مدیریت نشست‌ها.
Spacer	جداکننده بصری بین فیلدهای فرم، فقط برای کمک بصری و فاقد مقدار.
Sql	لیست کشویی ورودی‌ها بر اساس اجرای کوئری روی پایگاه داده جوملا، ستون اول نتایج به عنوان مقادیر استفاده می‌شود.
Status	لیست باکس وضعیت‌ها.
Subform	روشی برای استفاده از فرم‌های XML تو در تو یا بازاستفاده از فرم‌های قبلی در فرم فعلی.
Tag	نقطه ورود برای برچسب‌ها (با AJAX یا تو در تو).
Telephone	فیلد ورودی شماره تلفن.
Template Style	لیست کشویی سبک‌های قالب.
Text Area	منطقه متنی برای وارد کردن متن چند خطی.
Text	جعبه متنی برای ورود داده.
Time	لیست انتخاب اعداد صحیح با مقادیر شروع، پایان و گام مشخص.
Timezone	لیست کشویی مناطق زمانی.
Transition	لیست گروه‌بندی شده تمام انتقال‌های فرایند کاری از یک مرحله به مرحله بعد، بر اساس عنوان مرحله.
Url	فیلد متنی برای وارد کردن آدرس URL.
User Active	لیست وضعیت‌های فعال بودن کاربران.
User	فیلد مدال برای انتخاب کاربر از لیست، نمایش نام کاربر و ذخیره شناسه کاربری.
Usergroup List	لیست کشویی گروه‌های کاربری موجود.
User State	لیست وضعیت‌های کاربران.
Workflow Component Sections	لیست باکس شامل افزونه‌های فعال از نوع کامپوننت.
Workflow Condition	لیست کشویی یا لیست باکس شرایط فرایند کاری.
Workflow Stage	لیست گروه‌بندی شده تمام مراحل فرایند کاری، گروه‌بندی شده بر اساس فرایند کاری.

با کلیک بر روی هر یک از عناوین فیلد ها می توانید توضیحاتی کامل از آن را در سایت جوملا ببینید.

 

ویژگی‌های استاندارد فرم

بسیاری از ویژگی‌های فرم استاندارد به صورت مستقیم با ویژگی‌های HTML سازگار هستند و نیاز به توضیح بیشتر ندارند. توضیحات زیر به ویژگی‌هایی اختصاص دارد که معنای آن‌ها ممکن است کاملاً واضح نباشد.

برای دیدن فهرست کامل ویژگی‌های عمومی، می‌توانید کدهای موجود در `libraries/src/Form/FormField.php` و تابع `__set` را بررسی کنید. از آنجا که بسیاری از این ویژگی‌ها در فرم‌های مختلف جوملا قابل استفاده‌اند، اغلب به صورت مستقیم در توضیحات جزئی هر فیلد ذکر نمی‌شوند.

برخی از ویژگی‌ها:

- onchange: می‌توانید یک تابع جاوااسکریپت به آن بدهید که هنگام تغییر مقدار ورودی فراخوانی شود.

- autofocus: مشخص می‌کند که کدام ورودی هنگام بارگزاری صفحه فوکوس شود.

- data-xxx: ویژگی‌های data-* که روی عنصر ورودی تنظیم می‌شوند.

توضیح ویژگی‌های مهم:

- class

  این ویژگی به attribute کلاس HTML فیلد مربوط می‌شود. برای تعیین اعتبارسنجی سمت کاربر علاوه بر کاربرد معمول CSS استفاده می‌شود.

- description

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

  در بخش مدیریت، توضیحات توسط دکمه Toggle Inline Help نمایش یا مخفی می‌شوند. برای افزودن این قابلیت به فرم‌های کامپوننت خود: 

  1. دکمه Toggle Inline Help را به تولبار اضافه کنید: 

$toolbar = Toolbar::getInstance();
...
$toolbar->inlinehelp();

 

  2. در فایل XML فرم، تنظیمات زیر را اضافه کنید: 

 

<form>  
<config>  
<inlinehelp button="show"/>  
</config>  
...  
</form>

 

- filter

  مشخص می‌کند که فیلتر بر روی داده ورودی اعمال شود یا نه. فیلتر کردن داده‌ها برای جلوگیری از حملات تزریق (Injection) بسیار مهم است. 

  به طور پیش‌فرض، داده‌های متنی با استفاده از کلاس `\Joomla\Filter\InputFilter` فیلتر می‌شوند که برخی تگ‌ها و ویژگی‌های HTML را حذف می‌کند و این لیست ثابت است (قابل تغییر در تنظیمات کلی جوملا نیست). 

  جوملا فیلترهای دیگری نیز دارد که از آن جمله‌اند:

  - `intarray`: تبدیل داده به عددهای صحیح و حذف سایر کاراکترها.

  - `raw`: بدون فیلتر.

  - `rules`: برای فیلتر کردن فیلدهای نوع "rules" که برای تعیین مجوزها استفاده می‌شود.

  - `safehtml`: مشابه فیلتر پیش‌فرض، با قابلیت شخصی‌سازی برای بلوکه کردن تگ‌های بیشتر.

  - `tel`: فیلتر برای شماره تلفن‌ها.

  - `unset`: حذف همه چیز و بازگرداندن مقدار null.

  - `url`: حذف کاراکترهای نامعتبر در URL.

فیلتر سفارشی:

برای تعریف فیلتر سفارشی: 

1. کلاسی بسازید که اینترفیس \Joomla\CMS\Form\FormFilterInterface را پیاده‌سازی کند و متد `filter()` داشته باشد. 

2. فایل XML فرم را طوری تنظیم کنید که جوملا مکان کلاس شما را بشناسد، مثلاً: 

addfilterprefix="My\Component\Example\Site\Filter"

 3. در فیلد هدف از فیلتر با نام اختصاصی استفاده کنید: 

filter="myfilter"

 کد نمونه در کامپوننت com_exampleform موجود است.

- hint

  متن این ویژگی در placeholder (متن راهنما در داخل فیلد) مشاهده می‌شود.

-pattern

  عبارت منظم (regex) است که برای اعتبارسنجی سمت کاربر استفاده می‌شود.

- showon

  کنترل می‌کند که آیا یک فیلد بر اساس مقدار فیلد دیگر نمایش داده شود یا نه. به عنوان مثال: 

<field name="radiofield" type="radio" default="1" >  
  <option value="1">No showon</option>  
  <option value="2">This must be selected for showon field</option>  
</field>  
<field name="textfield" type="text" showon="radiofield:2"/>

 

  فیلد متنی وقتی نمایش داده می‌شود که فیلد رادیویی مقدار ۲ داشته باشد. 

  شرط می‌تواند با عملگرهای [AND] و [OR] ترکیب شود. همچنین می‌توان از ! برای معکوس کردن شرط‌ها استفاده کرد، مثلاً: 

  - `showon="radiofield!:2" ` نمایش زمانی که مقدار برابر ۲ نباشد. 

  - `showon="somefield!:"` نمایش اگر مقداری در فیلد somefield وجود داشته باشد (خالی نباشد).

- validate

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

- value

  مقدار `attribute = "value"` پیش‌فرض فیلد است و به عنوان مقدار در HTML استفاده می‌شود، مگر اینکه داده فرم به وسیله callback بارگذاری شود (در صورت بازنمایی فرم به دلیل مقدار نامعتبر، مقدار قبلی کاربر جایگزین می‌شود).

 

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

شما می‌توانید نوع فیلد اختصاصی خود را تعریف کنید (مثلاً "mycustom") و سپس در فایل XML تعریف فرم به آن ارجاع دهید:

<field type="mycustom" … />

برای این کار، باید کلاس خود را از `\Joomla\CMS\Form\FormField` که در مسیر `libraries/src/Form/FormField.php` است، توسعه دهید یا اینکه از یکی از انواع استاندارد فیلدهای فرم که خودش از FormField ارث‌بری کرده، استفاده کنید.

هنگامی که فرم سفارشی خود را تعریف می‌کنید، باید در فایل XML فرم، ویژگی `addfieldprefix` را نیز اضافه کنید تا جوملا بداند تعریف فیلد شما کجا قرار دارد. برای مثال:

namespace Mycompany\Component\Example\Administrator\Field;
class MycustomField extends FormField {
protected $type = 'Mycustom';
// استفاده از نوع بالا هنوز معمول است اما در کلاس‌های namespace شده الزامی نیست
}

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

<field addfieldprefix="Mycompany\Component\Example\Administrator\Field" type="mycustom" … />

ویژگی `addfieldprefix` می‌تواند هم در سطح تگ `<field>` و هم در یک تگ بالاتر که `<field>` را در بر می‌گیرد قرار گیرد.

مرور کلی طراحی فیلد در جوملا

قبل از اینکه وارد جزئیات کدنویسی کلاس فیلد سفارشی شویم، بهتر است بدانیم جوملا چگونه با فیلدها کار می‌کند.

کارکرد اصلی فیلد این است که:

1. ورودی آن ویژگی‌های `<field>` در فایل XML فرم باشد.

2. خروجی آن کد HTML مربوط به آن فیلد باشد تا در صفحه وب قرار گیرد.

برای این کار، کد فرم دو تابع را فراخوانی می‌کند:

- setup:  این تابع عنصر XML مربوط به `<field>`، مقدار فیلد و گروه فیلد (در صورت وجود داخل تگ `<fields>`) را دریافت می‌کند. معمولاً در اینجا ویژگی‌های مورد نیاز استخراج و در متغیرهای محلی ذخیره می‌شوند.

- renderField:   این تابع باید کد HTML مربوط به فیلد را بازگرداند.

کد HTML فیلد از ۳ بخش تشکیل شده است:

1. تگ label (برچسب) فیلد 

2. المنت ورودی (input) فیلد 

3. یک عنصر `<div>` که هر دو بخش بالا را در بر می‌گیرد

تابع `renderField` برای گرفتن این بخش‌ها از توابع زیر استفاده می‌کند:

- `getLabel()` برای گرفتن کد HTML مربوط به label 

- `getInput()` برای گرفتن کد HTML مربوط به المنت ورودی

سپس این بخش‌ها به عنوان متغیر به یک  layoutارسال می‌شوند تا درون `<div>` مناسب قرار بگیرند.

استفاده از Layout ها

بسیاری از فیلدهای استاندارد جوملا برای بخش‌های label و input از layout استفاده می‌کنند. داده‌هایی که در تابع `setup()` ذخیره شده‌اند، به عنوان `$displayData` به layout منتقل می‌شوند تا ویژگی‌هایی مانند `class`، `description` و غیره درست جایگذاری شوند، مطابق با تنظیماتی که در فایل XML فرم تعیین شده‌اند.

مثال‌هایی از فیلدهای سفارشی

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

فیلد سفارشی با ارث‌بری از FormField

اگر از کلاس FormField ارث‌بری کنید، باید متد `getInput` را پیاده‌سازی کنید که باید رشته HTML مربوط به فیلد را برگرداند. برای مثال، برای گرفتن کد فرودگاهی IATA با ۳ حرف:

 

protected function getInput()
{
    $html = "<input type='text' id='{$this->id}' name='{$this->name}' " .
            "minlength='3' maxlength='3' size='3' " .
            "oninput='this.value = this.value.toUpperCase()'/>";
    return $html;
}

 

ویژگی‌های تعریف‌شده در تگ `<field>` داخل فایل XML فرم، در تابع setup به خواص کلاس بارگذاری شده و از طریق `$this->name` و موارد مشابه در دسترس هستند.

مهم است که مقدار `name` تنظیم شود، زیرا این کلید برای ارسال داده‌ها از طریق HTTP POST است.

برچسب فیلد به طور پیش‌فرض از صفت `label` در تعریف XML تنظیم می‌شود. می‌توانید آن را بازنویسی کنید، مثلاً اگر می‌خواهید لینک اضافه کنید:

protected function getLabel()
{
    $html = "Enter the <a href='https://wikipedia.org/wiki/IATA_airport_code' target='_blank'>" .
            "3 character IATA airport code</a>";
    return $html;
}

در کد نمونه، نوع فیلد `custom1` مثالی از این روش است.

فیلد سفارشی با ارث‌بری از FormField و استفاده از لایه (Layout)

اگر متغیر نمونه `$layout` را مقداردهی کنید، این متغیر به عنوان لایه برای `getInput` استفاده می‌شود و نیازی به پیاده‌سازی تابع `getInput` ندارید:

class Custom2Field extends FormField
{
    protected $layout = 'custom2field';
}

جوملا داده‌های ویژگی‌های ذخیره شده در `$this` را به `$displayData` منتقل می‌کند تا بتوانید در فایل لایه متغیرهای مورد نظر مثل `$id` و `$name` را استخراج کنید. برای مثال، در فایل `layouts/custom2field.php` سایت:

<?php
defined('_JEXEC') or die;
extract($displayData);
?>
<input 
    type='text' 
    id='<?php echo $id?>' 
    name='<?php echo $name?>' 
    minlength='3' 
    maxlength='3' 
    size='3'
    oninput='this.value = this.value.toUpperCase()'/>

همچنین فراموش نکنید پوشه layouts سایت را در فایل manifest XML کامپوننت خود اضافه کنید!

نوع فیلد `custom2` نمونه‌ای از این حالت در کد نمونه است.

فیلد سفارشی با ارث‌بری از ListField

اگر می‌خواهید فیلد سفارشی شما یک لیست از گزینه‌ها را نمایش دهد، از `Joomla\CMS\Form\Field\ListField` ارث‌بری کرده و متد `getOptions` را بازنویسی نمایید:

use Joomla\CMS\Form\Field\ListField;
class Custom3Field extends ListField
{
    public function getOptions()
    {
        $options  = array("BFS", "HND", "YYZ");
        $options = array_merge(parent::getOptions(), $options);
        return $options;
    }
}

خط `$options = array_merge(parent::getOptions(), $options)` گزینه‌های موجود در تعریف XML فیلد را با گزینه‌های اضافه‌شده شما ادغام می‌کند.

نوع فیلد `custom3` نمونه‌ای از این روش است.

فیلد سفارشی با ارث‌بری از GroupedlistField

این نوع به شما امکان می‌دهد گزینه‌ها را گروه‌بندی کنید. مثلا اگر می‌خواهید کدهای فرودگاه را بر اساس کشورها گروه‌بندی کنید، می‌توانید متد `getGroups` را بازنویسی کنید:

 

use Joomla\CMS\Form\Field\GroupedlistField;
class Custom4Field extends GroupedlistField
{
    public function getGroups()
    {
        $groups['Japan'] = array("HND");
        $groups['Canada'] = array("XXY", "ABC", "DEF");
        $groups['Northern Ireland'] = array("BFS", "BHD");
        $groups = array_merge(parent::getGroups(), $groups);
        return $groups;
    }
}

 

نوع فیلد `custom4` در کد نمونه، مثالی از این نوع فیلد است. لینک دانلود