نسخهٔ ‏۲۴ اوت ۲۰۱۳، ساعت ۰۶:۳۲

مقدمه

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

معرفی

در جوملا 3.1.0 ویژگی‌ جدیدی تحت عنوان سیستم فیلد برچسب با امکانات زیر اضافه شده است:

• پشتیبانی از حالت چند زبانه
• ساختار برچسب‌های تو در تو
• یکپارچه شده در تمام محتوای اصلی
• انتخاب فیلد برچسب (حالت AJAX یا تو در تو)
• ایجاد برچسب شناور
• سازگاری با افزونه‌ها

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

با توجه به استفاده از سیستم‌های مشابه، می‌توان گفت این برچسب جدید در جوملا 3.1.0 برترهایی دارد:

• جستجو AJAX در برچسب.
• قرار دادن برچسب‌های سفارشی با فشردن کلید Enter یا کلید کاما.
• استفاده از پلاگین jQuery انتخاب شده به عنوان پایه که با هسته یکپارچه شده است.

استفاده عمومی

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

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

<source lang="php"> <field name="tags" type="tag"

   label="JTAG" description="JTAG_DESC"
   class="inputbox span12 small" multiple="true"

/> </source>

قرار گرفتن کلید type="tag" در بخشی از فایل بدون هیچ وابستگی که سیستم آنرا برای شما انجام می‌دهد.

در هنگام پردازش فرم سیستم وقایع زیر اتفاق خواهد افتاد:

1. بارگذاری jQuery.
2. بارگذاری پلاگین انتخاب شده.
3. بارگذاری پلاگین انتخاب-آژاکس.
4. بارگذاری کد JS سفارشی برای درج برچسب‌های سفارشی.

حالت فیلد

در com_tag گزینه‌هایی برای انتخاب و سفارشی سازی توسط کاربر وجود دارد که یک به یک آنرا توضیح می‌دهیم.

حالت خودکار

اگر شما حالت فیلد را در فیلد برچسب تعریف نکرده باشید از بخش تنظیمات عمومی com_tags برای تعریف فیلد استفاده می‌کند که بصورت پیش فرض بر روی AJAX تعریف شده است.

حالت AJAX

• جستجوهای فیلد برچسب بر اساس موارد تایپ شده توسط کاربر در فیلد برچسب.
• حداقل سه حرف مورد نیاز است برای راه اندازی اولین جستجوی AJAX.
• قرارداد فیلد برچسب سفارشی با فشردن کلید Enter یا کلید کاما. (اختیاری)
• همه برچسب‌های سفارشی موجود قرار داده شده در این فیلد در پایگاه داده ایجاد شده است.

برای تعریف فیلد جهت استفاده از حالت AJAX کد زیر باید تعریف شده باشد:

<source lang="php"> <field name="tags" type="tag" mode="ajax"

   label="JTAG" description="JTAG_DESC"
   class="inputbox span12 small" multiple="true"

/> </source>

حالت تو در تو

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

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

<source lang="php"> <field name="tags" type="tag" mode="nested"

   label="JTAG" description="JTAG_DESC"
   class="inputbox span12 small" multiple="true"

/> </source>

اجازه یا رد برچسب‌های سفارشی

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

توجه داشته باشید که در حالت تو در تو امکان ایجاد برچسب سفارشی نیست، بنابراین این تنظیمات مربوط به حالت AJAX می‌باشد.

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

حالت "اجازه" اضافه می‌کند در صورتی که در تنظیمات تعیین شده باشد.

به فیلد برچسب‌ اجازه داده می‌شود:

<source lang="php"> <field name="tags" type="tag" custom="allow"

   label="JTAG" description="JTAG_DESC"
   class="inputbox span12 small" multiple="true"

/> </source>

کد برچسب‌ها در حالتی که رد می‌شوند:

<source lang="php"> <field name="tags" type="tag" custom="deny"

   label="JTAG" description="JTAG_DESC"
   class="inputbox span12 small" multiple="true"

/> </source>

شما می‌توانید نمونه‌هایی از متغیرهای سفارشی مجاز را در بخش مدیریت محتوا ببینید. نمونه‌هایی از متغیرهایی که رد شده‌اند در برچسب آیتم‌های منو یافت می‌شود.

ابزار اضافی برای توسعه دهندگان

برای ادغام جستجوی AJAX با استفاده از پلاگین آژاکس ایجاد شده توسط رایان لفور کار را ادامه می‌دهیم. به نظر این کار جالبی است که مشابه یک افزونه اجرا می‌شود و می‌تواند برای سایر افزونه‌های دیگر نیز توسعه داده شود. تنها کاری که باید انجام داد سفارشی سازی آن است.

در این بخش توضیح داده شده که چگونه با استفاده از ادغام انتخاب-آژاکس نسبت به ساخت یک سیستم برچسب سفارشی اقدام کرد.

انتخاب-آژاکس

یک متد انتخاب-آژاکس در فایل زیر اضافه شده است:

libraries/cms/html/formbehavior.php

که اینگونه تعریف شده است:

<source lang="php"> /**

* Method to load the AJAX Chosen library
*
* If debugging mode is on an uncompressed version of AJAX Chosen is included for easier debugging.
*
* @param   JRegistry  $options  Options in a JRegistry object
* @param   mixed      $debug    Is debugging mode on? [optional]
*
* @return  void
*
* @since   3.0
*/

public static function ajaxchosen(JRegistry $options, $debug = null) { } </source>

گزینه‌های پذیرفته شده در JRegistry $ شی گزینه‌های اصلی هستند که دارای استاندارد jQuery AJAX و برخی از گزینه‌های خاص انتخاب-آژاکس می‌باشند:

minTermLength: حداقل تعداد حروف که باید قبل از فراخوانی آژاکس قرار بگیرد.

afterTypeDelay: چند میلی ثانیه بعد از تایپ کردن تا فراخوانی آژاکس صبر کنید.

jsonTermKey: کلید درخواست آژاکس برای استفاده از جستجوی پرس و جو (به طور پیش فرض به مدت)

همچنین یک گزینه انتخاب با انتخاب شی DOM به منظور مقداردهی اولیه به فیلد انتخاب–آژاکس به طور خودکار زمانیکه DOM آماده شده اضافه شده است.

برای مثال: # JS-myfield

ما می‌توانیم به عنوان مثال فیلد برچسب در فایل را فراخوانی کنیم:

<source lang="php">

libraries/cms/html/tag.php // Tags field ajax $chosenAjaxSettings = new JRegistry( array( 'selector' => $selector, 'type' => 'GET', 'url' => JURI::root() . 'index.php?option=com_tags&task=tags.searchAjax', 'dataType' => 'json', 'jsonTermKey' => 'like' ) ); JHtml::_('formbehavior.ajaxchosen', $chosenAjaxSettings);

</source>

بسیار ساده است نتایج AJAX برگردانده می‌شود، در مستندات انتخاب-آژاکس تعریف شده است.

برای نتایج استاندارد انتظار می‌رود نتایج فرمت زیر را دارا باشد:

<source lang="php"> [{"value": 3, "text": "Ohio"}] </source>

و نتایج گروه بندی:

<source lang="php"> [{

   group: true,
   text: "Europe",
   items: [
       { "value": "10", "text": "Stockholm" },
       { "value": "23", "text": "London" }
   ]

}, {

   group: true,
   text: "Asia",
   items: [
       { "value": "36", "text": "Beijing" },
       { "value": "20", "text": "Tokyo" }
   ]

}] </source>

فیلد برچسب سفارشی شده

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

اگر به سیستم برچسب K2 دقت کنید. با استفاده از این سیستم برچسب خود را با پارامتر جستجو "q" بکار ببرید.

مثال فیلد برچسب به شما کمک خواهد کرد:

<source lang="php">

/**

* This is just a proxy for the formbehavior.ajaxchosen method
*
* @param   string   $selector     DOM id of the tag field
* @param   boolean  $allowCustom  Flag to allow custom values
*
* @return  void
*
* @since   3.1
*/

public static function k2tagsfield($selector='#jform_tags', $allowCustom = true) { // Tags field ajax $chosenAjaxSettings = new JRegistry( array( 'selector' => $selector, 'type' => 'GET', 'url' => JURI::root() . 'index.php?option=com_k2&task=item.tags', 'dataType' => 'json', 'jsonTermKey' => 'q' ) ); JHtml::_('formbehavior.ajaxchosen', $chosenAjaxSettings); // Allow custom values ? if ($allowCustom) { JFactory::getDocument()->addScriptDeclaration(" (function($){ $(document).ready(function () { // Method to add tags pressing enter $('" . $selector . "_chzn input').keydown(function(event) { // tag is greater than 3 chars and enter pressed if (this.value.length >= 3 && (event.which === 13 || event.which === 188)) { // Create the option var option = $(); option.text(this.value).val('#new#' + this.value); option.attr('selected','selected'); // Add the option an repopulate the chosen field $('" . $selector . "').append(option).trigger('liszt:updated'); this.value = ; event.preventDefault(); } }); }); })(jQuery); " ); } }

</source>

البته سیستم برچسب K2 با برچسب و فرمت مورد انتظار باز خواهد گشت.

در تعریف این فیلد ما یک فراخوان برای کمک در لینک متد getInput اضافه کردیم:

<source lang="php">

// Get the field id $id = isset($this->element['id']) ? $this->element['id'] : null; $cssId = '#' . $this->getId($id, $this->element['name']);

// Load the ajax-chosen customised field JHtml::_('tag.k2tagsfield', $cssId, $this->allowCustom());

</source>

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

libraries/cms/form/field/tag.php

منبع:

http://magazine.joomla.org/issues/issue-apr-2103/item/1225-joomla-tag-field

ترجمه و ویرایش:

گروه آموزش - تیم جوملا فارسی

استفاده از مطالب دانشنامه جوملا فارسی - مامبو فارسی با ذکر منبع ( دانشنامه جوملا فارسی ) و لینک مستقیم به http://docs.joomlafarsi.com بلامانع است.