Использование тэгов в расширениях Joomla! 3.x

Система тегов в Joomla используется во всех Расширения ядра и предназначена для  легкой интеграции в другие расширения, которые используют стандартные шаблоны проектирования Joomla.

Использовать тэги в расширении довольно просто. Для этого требуется внести эти изменения в расширение:

• Зарегистрировать типы контента для видов расширения
• Добавить "Observer methods" в классы таблиц расширения
• Добавить поле тэгов к расширению в формах редактирования
• Добавить код вывода тэгов в файлы видов расширения
• При желании можно добавить метод пакетного создания тэгов в панели администрирования расширения

Регистрация типа контента для каждого вида

В Joomla! 3 типы контента, например, статьи, ссылки, контакты и т.п. регистрируются в таблице #__content_types с отдельной записью для каждого вида, например статьи, веб-ссылки, категории статей, категории веб-ссылок и т.п.

При установке вашего расширения необходимо создать новую запись для каждого вида, использующего тэги.

Вот структура таблицы #__content_types, каждый столбец будет описан в следующих разделах.

type_id

Это поле является автоинкрементным ключ записи.

type_title

Название для вашего Тип содержимого, например статьи, контактная, Weblink, Вы можете сделать это либо с помощью SQL или послеполетного путем создания экземпляра JTableContenttype. Не забывайте тип категории, если вы используете Joomla категории API.

type_alias

Строка, определяющая компонент и вид (что бы в запросе на страницу, как правило, соответствующие название модели), например com_contact.contact, com_weblinks.weblink.

table

Вам нужно определить, какие таблицы, используемые компонентом содержат записи, с тэгами. Например вид 'Контакт' компонента Контакты использует #__contact_details, а вид 'Ссылка' компонента Ссылок использует #__weblinks.

Каждый из этих компонентов используется класс для записи в таблице: ContactTableContact для компонента Контакты и WeblinksTableWeblink для компонента Ссылок. Вам будут нужны префиксы названий классов, например ContactTable, WeblinksTable.

Обратите внимание, что все типы категорий используют таблицу #__categories.

Ячейка table дает полную информацию о классе таблицы в виде объекта JSON с двумя элементами. Первый элемент представляет свою ​​"особую" таблицу, второй - необязательную общую таблицу (по умолчанию выполнится JTableCorecontent).

Вот запись JSON для типа содержимого веб-ссылка:

 
{
  "special": {
    "dbtable": "#__weblinks",
    "key": "id",
    "type": "Weblink",
    "prefix": "WeblinksTable",
    "config": "array()"
  },
  "common": {
    "dbtable": "#__ucm_content",
    "key": "ucm_id",
    "type": "Corecontent",
    "prefix": "JTable",
    "config": "array()"
  }
}

Значения, которые включены в запись:

Эта информация позволяет системе тэгов (и другим интерфейсам API) производить легкий доступ к таблицам компонента.

Если вы используете категории Joomla, убедитесь, что вы создали тип категории вашего компонента так, что они могут быть помечены тэгами. В Joomla 3.1 и 3.1.1 есть ошибка, где поле тэгов покажет, даже если нет типа контента, но это исправляется в 3.1.4.

Примечания

• Именем таблицы для главной таблицы является #__ucm_content; это неверно для 3.1 и 3.1.1, где эти данные не используется. Данные используются начиная с 3.1.4.

• Поле type_title потенциально может быть использовано для отображения заголовков типов, хотя это не реализовано в настоящее время, за исключением области ContentType. Обычно оно должно начинаться с заглавной буквы, писаться на английском языке. Смотри заметку о том, как сделать это поле переводимым: для того, чтобы ваши имена типов были переводимыми надо добавить COM_TAGS_CONTENT_TYPE_+type_title="Type Title" в ini и sys.ini языковых файлах.

rules

Правила в настоящее время не используется. Это поле, вероятно, будет удалено в пользу asset_id для каждого типа, в настоящее время вы можете игнорировать это поле, которое будет управляться JTable.

field_mappings

Эта запись отображает соответствие имен столбцов в таблице вашего компонента с набором стандартной Joomla! имен. Это отображение хранится в виде массива JSON с первым "common"

элементом с общими полями и вторым  "special" элементом, отображающим другие поля из таблицы.

Вот запись field_mappings для Content Type Баннер (выбран потому, что он является богаче пример, чем статьи или WebLink). Обратите внимание, что 'общие' отображения, которые не имеют никакого эквивалента включены как «нуль» (оставляя их пустыми может вызвать SQL вопросы); имена и значения в "специальной" элемента всего матча, как они ограничены к этому компоненту.

{
  "common": {
    "core_content_item_id": "id",
    "core_title": "name",
    "core_state": "published",
    "core_alias": "alias",
    "core_created_time": "created",
    "core_modified_time": "modified",
    "core_body": "description",
    "core_hits": "null",
    "core_publish_up": "publish_up",
    "core_publish_down": "publish_down",
    "core_access": "access",
    "core_params": "params",
    "core_featured": "null",
    "core_metadata": "metadata",
    "core_language": "language",
    "core_images": "images",
    "core_urls": "link",
    "core_version": "version",
    "core_ordering": "ordering",
    "core_metakey": "metakey",
    "core_metadesc": "metadesc",
    "core_catid": "catid",
    "core_xreference": "null",
    "asset_id": "null"
  },
  "special": {
    "imptotal": "imptotal",
    "impmade": "impmade",
    "clicks": "clicks",
    "clickurl": "clickurl",
    "custombannercode": "custombannercode",
    "cid": "cid",
    "purchase_type": "purchase_type",
    "track_impressions": "track_impressions",
    "track_clicks": "track_clicks"
  }
}

Как минимум для общих полей необходимо сопоставить: content_item_id, alias и title для того, чтобы успешно создавать URL-адреса для списков элементов с тэгами. Вы также, вероятно, захотите сопоставить: access, status и language поля. Специальные поля являются необязательными.

Примечание

• API-интерфейсы JHelperTags и JUcm в 3.1.1 поддерживают массивы для этого поля, но по состоянию на 3.1.4 поддерживаются массивы или объекты. По умолчанию объекты.

router

Это необязательное поле включает имя статического метода помощника маршрутизатора для этого типа, найденного в фронт-энд папке помощников компонента, например WeblinksHelperRoute::getWeblinkRoute.

Если в вашем компоненте нет пользовательского маршрутизатора, то тэги возвращаются к правилам в JHelperRoute.

Если вы только храните данные в #__ucm_content вы в конечном итоге можете оставить поле маршрутизатор пустым, хотя эта опция еще не реализована.

content_history_options

Этот раздел был добавлен в Joomla! 3.2 как связь с  компонентом истории контента.

Вот запись для типа контента Баннер:

{
  "formFile": "administrator\/components\/com_banners\/models\/forms\/banner.xml",
  "hideFields": [
    "checked_out",
    "checked_out_time",
    "version",
    "reset"
  ],
  "ignoreChanges": [
    "modified_by",
    "modified",
    "checked_out",
    "checked_out_time",
    "version",
    "imptotal",
    "impmade",
    "reset"
  ],
  "convertToInt": [
    "publish_up",
    "publish_down",
    "ordering"
  ],
  "displayLookup": [
    {
      "sourceColumn": "catid",
      "targetTable": "#__categories",
      "targetColumn": "id",
      "displayColumn": "title"
    },
    {
      "sourceColumn": "cid",
      "targetTable": "#__banner_clients",
      "targetColumn": "id",
      "displayColumn": "name"
    },
    {
      "sourceColumn": "created_by",
      "targetTable": "#__users",
      "targetColumn": "id",
      "displayColumn": "name"
    },
    {
      "sourceColumn": "modified_by",
      "targetTable": "#__users",
      "targetColumn": "id",
      "displayColumn": "name"
    }
  ]
}

Создание записи

Можно делать записи в программе установки в одном из трех способов:

• в postflight методе установочного скрипта
• путем создания экземпляра JTableContenttype и добавления строки или
• с помощью SQL, чтобы создать запись непосредственно

Изменение класса таблицы вашего компонента (или классы, если у вас есть несколько таблиц)

Добавьте следующее в вашем JTable конструктор:

$this->_observers = new JObserverUpdater($this); JObserverMapper::attachAllObservers($this);

Добавление этой строки больше не нужно после 3.1.4 Пожалуйста, прочитайте историю документа для этой страницы, если вы должны поддерживать 3.1.0 или 3.1.1.

Для Joomla 3.2 нужно добавить эту строку: (Не забудьте заменить weblinks вашим именем компонента)

JObserverMapper::addObserverClassToClass('JTableObserverTags', 'WeblinksTableWeblink', array('typeAlias' => 'com_weblinks.weblink'));

Добавить теги к методу getItem() модели

Примечание: это требуется только в 3.1.0 и 3.1.1. Это не должно быть использована в 3.1.4 или более поздней версии. Пожалуйста, прочтите историю этой странице, если вы нужны инструкции для более старых версий.

Добавление поля тегов в виды редактирования

В любых макетах редактирования, где вы хотите использовать эту функцию, вы должны добавить поле в XML и соответствующих макетах при необходимости. Основные макеты используют JLayout для управления тэгами,тот же макет может быть использован любым расширением.

Обновление: Обратите внимание, что только в 3.1.1  есть специальная обработка этого в ядре. Теги в виде редактирования ДОЛЖНЫ быть частью метаданных <fields></fields> группы. Ядро обеспечивает два JLayouts чтобы помочь вам управлять стандартными форматами - один (details) для метаданных и один для боковой панели, которая включает вкладки. В обновлении расширение 3.1.4 вам может понадобиться, чтобы исправить настроить вида редактирования.

В 3.1.4 или позднее эта специальная обработка не требуется. Наилучшим вариантом является использование стандартных JLayouts так как это обеспечивает последовательную процедуру для пользователей.

                <field name="tags" type="tag"
                        label="JTAG" description="JTAG_DESC"
                        class="inputbox span12 small" multiple="true"
                >
                </field>

Поле подгружает все требуемые библиотеки JavaScript. Вам не нужно беспокоиться об этом.

Поле поддерживает два режима:

• Nested tags mode. Иерархический список тэгов. Не поддерживает создание тэгов налету.
• AJAX mode. Тэги ищутся во время ввода пользователем  (мин. 3 символа необходимы для запуска поиска AJAX). Пользовательские тэги добавляются нажатием на ENTER или запятую. Тэги показывают глобальный маршрут/путь. Пример: grandpa/parent/tag

Поле может быть настроено для использования com_tags настроек Tag field mode , чтобы определить его режим. Для принудительной установки режима поля мы должны добавить mode="ajax" или mode="nested" к определению поля тегов.

Пример принудительного режима AJAX:

                <field name="tags" type="tag" mode="ajax"
                        label="JTAG" description="JTAG_DESC"
                        class="inputbox span12 small" multiple="true"
                >
                </field>

Поле также включает атрибут разрешить / запретить пользователю вводить произвольные значения тэгов. В данный момент это работает только в режиме AJAX. Атрибут должен быть добавлен в определении поля как **custom="allow"** или **custom="deny"**

Пример поля с запретом произвольных тэгов:

                <field name="tags" type="tag" mode="ajax" custom="denied"
                        label="JTAG" description="JTAG_DESC"
                        class="inputbox span12 small" multiple="true"
                >
                </field>

если он еще не введен. Обычно multiple должно быть true, если у вас нет особых причин делать иначе. В основных компонентах в панели администрирования, поле тэгов находится в группе, показанной справа, ниже поля языка.

Примечание: По состоянию на 3.1.2, если вы хотите использовать поле для обозначения родительских тэгов, вы должны добавить parent="parent" в XML определение поля.

Подготовка вида

Добавьте в ваш view.html.php  перед загрузкой макета:

$item->tags = new JHelperTags;
$item->tags->getItemTags('com_newsfeeds.newsfeed.' , $this->item->id);

Первый параметр должен соответствовать типу в таблице типов. Второй параметр является первичным ключом, с которым эта запись хранится в таблице. Это может быть использовано в любом виде, где вы хотите вывести теги связанные с этим элементом.

Настройка просмотра

В любом макете, где вы хотите отобразить теги, связанные с материалом введите:

                <?php $this->item->tagLayout = new JLayoutFile('joomla.content.tags'); ?>
                <?php echo $this->item->tagLayout->render($this->item->tags->itemTags); ?>

Измените имена объектов и свойств по мере необходимости.

Вы, скорее всего, хотите добавить параметр show_tags параметрам элементов, параметрам пунктов меню и конфигурации компонентов по мере необходимости для вашего использования.

        <?php if ($this->params->get('show_tags', 1)&& !empty($this->item->tags)) : ?>
                <?php $this->item->tagLayout = new JLayoutFile('joomla.content.tags'); ?>
                <?php echo $this->item->tagLayout->render($this->item->tags->itemTags); ?>
        <?php endif;?>

Пакетная обработка

Если вы хотите добавить возможность делать пакетное добавление тэгов в виде списка материалов,  добавьте тег к default_batch layout

        <div class="control-group">
                        <div class="controls">
                                <?php echo JHtml::_('batch.tag');?>
                        </div>
                </div>

И добавить тег к классу кнопки в модальном окне (Не полностью необходимо на данный момент, но хорошо для потенциальных будущих изменений, например, если добавляется unTag.)

 
<button class="btn"  type="button" onclick="document.id('batch-category-id').value='';document.id('batch-access').value='';document.id('batch-language-id').value='';document.id('batch-user-id').value='';document.id('batch-tag-id)').value=''" data-dismiss="modal">

Добавьте метод пакетной обработки к вашей модели, если вы не расширялись от JModelAdmin или переопределяли метод пакетной обработки.

       
         /**
         * Batch tag a list of item.
         *
         * @param   integer  $value     The value of the new tag.
         * @param   array    $pks       An array of row IDs.
         * @param   array    $contexts  An array of item contexts.
         *
         * @return  void.
         *
         * @since   3.1
         */
        protected function batchTag($value, $pks, $contexts)
        {
                $tagsHelper = new JHelperTags();
                $tagsHelper->tagItems($value, $pks, $contexts);
 
                return true;
        }

И измените ваш метод пакетного добавления

          
                if (!empty($commands['tag']))
                {
                        if (!$this->batchTag($commands['tag'], $pks, $contexts))
                        {
                                return false;
                        }
 
                        $done = true;
                }

Обращайте внимание на любые JSON строки, которые вам нужно специально обработать в пакетной обработке - помните, что вы сохраняете копию в основных областях, и вы должны сохранить работоспособность.

Вот и все премудрости тэгосторения Joomla.

Перевод статьи из документации Joomla.