Создание собственных файлов интеграции Komento

В данном руководстве мы рассмотрим пример создания собственных файлов интеграции для компонента комментариев Komento.

Файлы интеграции Komento

Создать файлы интеграции довольно просто. Нужно знать PHP и, конечно же, компонент, с которым нужно провести интеграцию.

1. Создание файла интеграции

Komento будет искать следующие файлы в таком порядке:

/path/components/com_yourcomponent/komento_plugin.php
/path/components/com_komento/komento_plugins/com_yourcomponent.php

Важно! Не обязательно создавать файлы в обеих папках. Нужен только один из этих файлов.

2. Задание имени классу

Название класса должно всегда начинаться с Komento. Например, если компонент называется com_eg, название будет следующим:

require_once( JPATH_ROOT . DS . 'components' .DS . 'com_komento' . DS . 'komento_plugins' . DS . 'abstract.php' );
 
 class KomentoComEgg extends KomentoExtension
 {
 }

Название класса не чувствительно к регистру.

3. Параметры класса

У класса должны быть следующие параметры:

component - этот параметр должен соответствовать значению имени компонента в константе.
_item - этот параметр (объект) хранит все нужные Komento параметры. (Обратитесь к методу "load" в классовых методах)
_map - этот параметр (массив) сохраняет все карты ключа нужного параметра элемента из стандартного ключа Komento в кастомный ключ компонента.

4. Классовые методы

Слово «статья» в документе ниже подразумевает только намек на понятие «блог пост», «событие», «продукт», в зависимости от того, чем является ваш компонент.

load - этот метод подгружает основные параметры статьи.

Komento нужно 6 параметров:

• Id статьи
• Название статьи
• Id категории статьи
• Пермалинк статьи
• Количество обращений к статье (опционально)
• Автор статьи (опционально)

Параметры статьи могут иметь свой собственный ключ. Нужно всего лишь получить обратно свойства _map.
getContentIds - подгружает все id статей, отсортированных по id категории.
getCategories - подгружает id категорий компонента.
isListingView - указывает Komento является ли страница домашней или разметкой категорий. Полезно, когда нужно, чтобы Komento выводит комментарий/считал посещения.
isEntryView - указывает Komento на этой ли странице должна отображаться форма комментария.
onExecute - главный метод, прикрепляющий Komento к статье.

getContentId - возвращает id статьи. Таким способом переопределяется отображение id статьи в свойствах _map.
getContentTitle - возвращает название статьи. Таким способом переопределяется отображение названия статьи в свойствах _map.
getContentHits - возвращает количество посещений статьи. Таким способом переопределяется отображение количества обращений к статье в свойствах _map.
getCategoryId - возвращает id категории статьи. Таким способом переопределяется отображение id категории статьи в свойствах _map.
getContentPermalink - возвращает пермалинк статьи. Таким способом переопределяется отображение пермалинка статьи в свойствах _map.
getAuthorId - возвращает id автора статьи. Таким способом переопределяется отображение id автора статьи в свойствах _map.
getAuthorName - возвращает имя автора статьи. Если этот метод не задан, по умолчанию Komento сгенерирует имя автора на основе пользовательской таблицы Joomla.
getAuthorAvatar - возвращает аватар автора статьи.
getCommentAnchorId - возвращает константу с именем анкера, сгенерированным сверху Komento. Используется, если компонент имеет ссылку «переходить к комментариям» ("jump to comments"), ведущую к определенному хэш-анкеру.
prepareLink - используется для подготовки пермалинка статьи, для проверки корректности ссылки. Не рекомендуем переопределять эту функцию.
onBeforeLoad - используется, если нужны действия, предшествующие загрузке Komento.
onAfterLoad - используется, если нужны действия, следующие после загрузки Komento.
onRollBack - используется, если нужны действия, после неудачной загрузки Komento. Полезно для возвращения некоторых параметров в оригинальное состояние.
getEventTrigger - если вы используете контент-триггеры Joomla's (onContentPrepare или onContentAfterDisplay), возможно нужно будет указать, какой именно триггер должен подгружать Komento.

5. Примеры шаблонов

// Always load abstract class by uncommenting the following line
 require_once( JPATH_ROOT . DS . 'components' . DS . 'com_komento' . DS . 'komento_plugins' . DS .'abstract.php' );
 
 // Load all required files by component
 require_once( 'COM_SAMPLE_DEPENDENCIES' );
 
 class KomentoComsample extends KomentoExtension
 {
 public $component = 'com_sample';
 public $_item;
 
 public $_map = array(
 'id' => 'id_field',
 'title' => 'title_field',
 'hits' => 'hits_field',
 'created_by' => 'created_by_field',
 'catid' => 'catid_field',
 'permalink' => 'permalink_field'
 );
 
 public function load( $cid )
 {
 static $instances = array();
 
 if( !isset( $instances[$cid] ) )
 {
 // populate $this->_item with:
 // id_field
 // title_field
 // hits_field
 // created_by_field
 // catid_field
 // permalink_field
 
 $instances[$cid] = $this->_item;
 }
 
 $this->_item = $instances[$cid];
 
 return $this;
 }
 
 public function getContentIds( $categories = '' )
 {
 $articleIds = array();
 
 if( empty( $categories ) )
 {
 // without category filters
 // return all valid article ids
 }
 else
 {
 if( is_array( $categories ) )
 {
 $categories = implode( ',', $categories );
 }
 
 // with category filters
 // return article ids in that category
 }
 
 return $articleIds;
 }
 
 public function getCategories()
 {
 $categories = array();
 
 // optional. populate tree listing
 foreach( $categories as &$row )
 {
 $repeat = $row->level;
 $row->treename = str_repeat( '. ', $repeat ) . ( $row->level > 0 ? '|_ ' : '' ) . $row->title;
 }
 
 return $categories;
 }
 
 // to determine if is listing view
 public function isListingView()
 {
 return JRequest::getCmd('view') == 'listing';
 }
 
 // to determine if is entry view
 public function isEntryView()
 {
 return JRequest::getCmd('view') == 'article';
 }
 
 public function onExecute( &$article, $html, $view, $options = array() )
 {
 // $html is the html content generated by Komento
 return $html;
 }
 }

6. Вызов Komento

Когда готов абстрактный слой интеграции и все параметры выставлены, можно вызвать Komento в коде PHP.

require_once( JPATH_ROOT . DS . 'components' . DS . 'com_komento' . DS . 'bootstrap.php' );

Komento::commentify( 'com_egg', $article, $options );

7. Использование триггеров Joomla

Эта часть опциональна!
Не обязательно размещать код для вызова Komento прямо в вашем исходном коде, если используется триггер Joomla (даже если используется собственное название триггера).
Если используется свое имя триггера, нужно будет создать отдельный плагин. Плагин контента Komento поддерживает несколько стандартных плагинов контента Joomla.

Например:

• onContentPrepare/onPrepareContent
• onContentAfterDisplay/onAfterDisplayContent

Убедитесь, что в абстрактном слое задан метод.

public function getEventTrigger()
 {
 return 'onYourCustomEventName';
 }

Пример плагина шаблона.

class plgContentYourPluginName extends JPlugin
 {
 public function onYourCustomEventName( $article, $params )
 {
 $triggerName = __FUNCTION__;
 require_once( $JPATH_ROOT . DS . 'components' . DS . 'com_komento' . DS . 'bootstrap.php' );
 
 // if you would like to perform a check to make sure this is the trigger that should call Komento
 // make sure that you have getEventTrigger method in your abstract layer file.
 $application = Komento::loadApplication( 'com_egg' );
 if( !$application->getEventTrigger() == $triggerName )
 {
 return false;
 }
 
 $options = array(
 'trigger' => $triggerName;
 );
 
 // Komento::commentify will return the HTML content of Komento, it is up to your component that triggers this event to echo the HTML content.
 // $article has to be an object that consist of the following properties:
 // id, catid, introtext, text
 return Komento::commentify( 'com_egg', $article, $option );
 }
 }