Component's Plugin
Creating your own Komento integration is fairly simple. You have to be familiar with PHP and of course the component that you'd like to integrate with.
Let's start creating your first Komento component's plugin. By default, Komento will looks for the component's plugins at /components/com_komento/komento_plugins/. In this folder, you will find all the Komento component's plugins.
- Class Definition
- Constructor
- Mandatory Methods
- Optional Methods
- Trigger Methods
- Implementation
- Sample Class
Creating New Komento Component's Plugin File
Create your own Komento component's plugins in this folder (defined above). Your component's plugins must be named as the same as the component's name for future reference. As example, you have created a Komento component plugin named com_egg as illustrated in the screenshot below.
Class Definition
After you have created the plugin as explained above, you may now start writing your codes. Make sure the class name should always begin with Komento. For instance, Komento must be prepend before your component's name on the class definition: class KomentoComegg.
<?php
defined('_JEXEC') or die('Unauthorized Access');
// Require the abstract class for Komento plugin.
require_once(__DIR__ . '/abstract.php');
class KomentoComegg extends KomentoExtension
{
// This property (object) stores all the required properties by Komento.
public $_item;
// This property (array) stores all the key mappings of the required item properties
// to map from Komento's default key to your component's custom key.
public $_map = array('id' => 'id',
'title' => 'title',
'hits' => 'hits',
'created_by' => 'created_by',
'catid' => 'catid',
'permalink' => 'permalink');
public function __construct($component)
{
parent::__construct($component);
}
public function load($cid)
{
static $instances = null;
// Load article object to $instances[$cid].
if (!isset($instances[$cid])) {...}
$this->_item = $instances[$cid];
return $this;
}
?>
Constructor Method
If your component requires an extra file, you may load it on the constructor method.
Make sure to call parent::__construct($component) at the end of constructor method.
<?php
public function __construct($component)
{
$this->addFile(JPATH_ROOT . '/components/com_egg/config.php');
parent::__construct($component);
}
?>
Mandatory Methods
This plugin's class must contains all the following methods. These methods are the Komento core functions required to get all the necessary data.
Function load is essential to Komento in order to load single article to $_item.
<?php
// This method should load the article's main properties based on the article ID
// using the mapping items defined in $_map.
public function load($cid)
{
static $instances = null;
// Load and populate $this->_item
if(!isset($instances[$cid])){...}
$this->_item = $instances[$cid];
return $this;
}
?>
Function getContentIds usually used to retrieve all article ids for the specified categories.
<?php
// This method should load all the article ids filtered by category ids.
public function getContentIds($categories = '')
{
// Load Komento database library
$db = KT::db();
$query = '';
if(empty($category)){$query = 'SELECT...';}
else{$query = 'SELECT...';}
// Set the query to the database and retrieve the data.
$result = $db->setQuery($query)->loadObjectList();
return $result;
}
?>
Function getCategories is quite an important method in retrieving categories in your component. You need to know whether your component has a single level categories or nested categories which most of Joomla component do have. You have to code this method accordingly.
<?php
// This method should load all the categories ids on the component.
public function getCategories()
{
// Load Komento database library
$db = KT::db();
$query = 'SELECT...';
// Set the query to the database and retrieve the data.
$categories = $db->setQuery($query)->loadObjectList();
return $categories;
}
?>
Function isListingView is a method in which determine whether Komento comment form should not be rendered on this view.
<?php
// This method lets Komento know if this is the front page or category layout.
// Useful when you just want Komento to output the comment / hit count.
public function isListingView()
{
$views = array('featured', 'category', 'categories', 'archived', 'frontpage');
return in_array(JFactory::getApplication()->input->getCmd('view'), $views);
}
Function isEntryView is the opposite of the above. This method determine whether Komento comment form should be displayed on this view.
<?php
// This method lets Komento know if this is the page that the comment form should be displayed on.
public function isEntryView()
{
return JFactory::getApplication()->input->getCmd('view') == 'article';
}
Function onExecute is the main method that appends Komento on the article. This method outputs the HTML code upon execution. You may also use it to append code to an article object.
<?php
// This method is the main method that appends Komento on the article
public function onExecute(&$article, $html, $view, $options = array())
{
// $html is the html content generated by komento (includes listing and form)
return $html;
}
?>
Optional Methods
These methods are optional. For some cases, you might need these methods to further manipulate the integration between Komento and your component.
<?php
// This method should return the id of the article.
// This overwrites the article id mapping in $_map properties.
function getContentId(){...}
// This method should return the title of the article.
// This overwrites the article title mapping in $_map properties.
function getContentTitle(){...}
// This method should return the hits of the article.
// This overwrites the article hits mapping in $_map properties.
function getContentHits(){...}
// This method should return the category id of the article.
// This overwrites article category id mapping in $_map properties.
function getCategoryId(){...}
// This method should return the permalink of the article.
// This overwrites the article permalink mapping in $_map properties.
function getContentPermalink(){...}
// This method should return the author's id of the article.
// This overwrites the author's id mapping in $_map properties.
function getAuthorId(){...}
// This method should return the author's name of the article.
// If this method is not defined, Komento will generate the author's name from Joomla's user.
function getAuthorName(){...}
// This method should return author's avatar of the article.
function getAuthorAvatar(){...}
// This method should return a string with the anchor name generated at the top of Komento.
// This is useful in navigating to the particular comment on a page.
function getCommentAnchorId(){...}
// This method is used to prepare and format the article permalink.
// NOTE: We do not recommend you to overwrite this function.
function prepareLink($link){...}
// Use this method if and only if there are actions needed before loading Komento.
function onBeforeLoad($eventTrigger, $context, &$article, &$params, &$page, &$options){...}
// Use this method if and only if there are actions needed after loading Komento.
function onAfterLoad($eventTrigger, $context, &$article, &$params, &$page, &$options){...}
// This is useful to revert some of the properties state to the original state.
// Use this method if and only if there are actions needed after failed to load Komento.
function onRollBack($eventTrigger, $context, &$article, &$params, &$page, &$options){...}
// This method should return the content triggers of which you're using/triggering.
// If you're using Joomla's content trigger as such; onContentPrepare or onContentAfterDisplay,
// or your own custom trigger, then you might want to specify which trigger should Komento load.
function getEventTrigger(){...}
// This method should be used if there are actions needed when Komento is disabled through a detected
// parameter {KomentoDisabled} in the content.
function onParameterDisabled($eventTrigger, $context, &$article, &$params, &$page, &$options){..}
// This method should return a custom component name.
// By default this method will return JText of 'COM_KOMENTO_COM_EGG' from Komento language file.
function getComponentName(){...}
// This method should return a custom component image url. By default this method will return image of
// '/administrator/components/com_komento/assets/images/docs/komento/components/com_egg.png'.
function getComponentIcon(){...}
// This method should return a custom component theme overrides path. By default this method will return
// path at '/components/com_egg/komento'.
function getComponentThemePath(){...}
?>
Trigger methods
These are advanced methods where you can use them to further extend Komento's feature or usability. Refer to the Trigger documentation for more information.
Implementation
After you have the integration abstract layer ready and properly in place, you can now call Komento in your template file; on comment section. This to render Komento form.
<?php
require_once(JPATH_ROOT . '/components/com_komento/bootstrap.php');
echo KT::commentify('com_egg', $article, $options);
?>
This method commentify() expects an article object which generated by your component consisting all the necessary properties. It return a html form of Komento to be displayed on the site.
id or $_map['id']
Article ID (This should follow the class method of _map that contains the mapping to the 'id' name).catid
Category ID that the article belongs to.introtext
Introtext of the content (typically content before the "Read More" break).text
Full content of the article.
Sample Class Com_sample
<?php
/**
* @package Komento
* @copyright Copyright (C) 2010 - 2017 Stack Ideas Sdn Bhd. All rights reserved.
* @copyright Copyright (C) 2017 Jon Brown @ QuantumWarp.com
* @license GNU/GPL, see LICENSE.php
* Komento is free software. This version may have been modified pursuant
* to the GNU General Public License, and as distributed it includes or
* is derivative of works licensed under the GNU General Public License or
* other free or open source software licenses.
* See COPYRIGHT.php for copyright notices and details.
*/
// No direct access
defined('_JEXEC') or die('Restricted access');
// Always load abstract class - This file also includes extra information about the functions here and the advanced functions not covered
//require_once(JPATH_ROOT . DIRECTORY_SEPARATOR . 'components' . DIRECTORY_SEPARATOR . 'com_komento' . DIRECTORY_SEPARATOR . 'komento_plugins' . DIRECTORY_SEPARATOR .'abstract.php');
require_once(JPATH_ROOT . '/components/com_komento/komento_plugins/abstract.php');
class KomentoComsample extends KomentoExtension
{
/******************************************************
*
* START
* [BASIC FUNCTIONS (METHODS)]
* These functions are mandatory
*
******************************************************/
// This property (object) stores all the required properties by Komento
public $_item;
// This property (array) stores all the key mappings of the required item properties to map from Komento's default key to your component's custom key
public $_map = array(
// not needed with custom getContentId()
'id' => 'id_field',
// not needed with custom getContentTitle()
'title' => 'title_field',
// not needed with custom getContentHits()
'hits' => 'hits_field',
// not needed with custom getAuthorId()
'created_by' => 'created_by_field',
// not needed with custom getCategoryId()
'catid' => 'catid_field',
// not needed with custom getContentPermalink()
'permalink' => 'permalink_field'
);
// Constructor - Add all required files for your component here and run its constructor
public function __construct($component)
{
// Load all required files by component
// $this->addFile(your component's files);
// $this->addFile(JPATH_ADMINISTRATOR . '/components/com_sample/config.php');
// This must be left at the end of this constructor function
parent::__construct($component);
}
// This method should load the article's main properties based on article ID
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
// Create a Database Object
$db = KT::getDBO();
// Create SQL query to load a single article
$query = 'SELECT `id_field`, `title_field`, `hits_field`, `created_by_field`, `catid_field` FROM `#__ARTICLE_TABLE` WHERE `ARTICLE_ID` = ' . $db->quote($cid);
$db->setQuery($query);
// Run the single article query and if there are no objects to load call the onLoadArticleError event
if (!$this->_item = $db->loadObject()) {
return $this->onLoadArticleError($cid);
}
// Generate the permalink for this article
$this->_item->permalink_field = 'index.php?options=com_sample&view=article&id=' . $this->_item->id_field;
// Call the prepareLink function and leave the rest to us
// Unless you have custom SEF methods, then use "getContentPermalink" function to overwrite
$this->_item->permalink_field = $this->prepareLink($this->_item->permalink_field);
$instances[$cid] = $this->_item;
}
$this->_item = $instances[$cid];
return $this;
}
// This method should load all the article IDs filtered by category IDs
public function getContentIds($categories = '')
{
// Create a Database Object
$db = KT::getDBO();
// Make sure the query is empty
$query = '';
// If no categories are supplied then load all article IDs
if (empty($categories)) {
$query = 'SELECT `id_field` FROM `#__ARTICLE_TABLE` ORDER BY `id_field`';
}
// If categories are supplied then load all article IDs for articles belonging to those categories
else
{
if (is_array($categories)) {
$categories = implode(',', $categories);
}
$query = 'SELECT `id_field` FROM `#__ARTICLE_TABLE` WHERE `catid_field` IN (' . $categories . ') ORDER BY `id_field`';
}
// Run the query and return the results as an array
$db->setQuery($query);
return $db->loadResultArray();
}
// This method should load all the category IDs of the component
// Make sure you select 'Single Level' or 'Nested' categories
public function getCategories()
{
// Create a Database Object
$db = KT::getDBO();
// Single Level Categories
//$query = 'SELECT `id`, `title` FROM `#__CATEGORY_TABLE`';
// Nested Categories
$query = 'SELECT `id`, `title`, `level`, `parent_id` FROM `#__CATEGORY_TABLE`';
// Run query and return categories
$db->setQuery($query);
$categories = $db->loadObjectList();
// Populate category tree for Komento Admin Integration Tab for this plugin (optional)
// This is used in Komento where you select which categories the plugin should be active on etc...
foreach ($categories as &$row) {
// Single Level Categories
//$row->level = 0;
// Nested Categories
$repeat = ($row->level - 1 >= 0) ? $row->level - 1 : 0;
// Build and Add the Category Tree entry
$row->treename = str_repeat('.   ', $repeat) . ($row->level - 1 > 0 ? '|_ ' : '') . $row->title;
}
return $categories;
}
// This method lets Komento know if this is the front page or category layout (Determine if is listing view)
public function isListingView()
{
$views = array('featured', 'category', 'categories', 'archive', 'frontpage');
return in_array(JFactory::getApplication()->input->getCmd('view'), $views);
}
// This method lets Komento know if this is the page that the comment form should be displayed on (Determine if is entry view)
public function isEntryView()
{
return JFactory::getApplication()->input->getCmd('view') == 'article';
}
// This method is the main method that appends Komento on the article
public function onExecute(&$article, $html, $view, $options = array())
{
// $html is the html content generated by komento (includes listing and form)
// Select 1 of the following outputs
// This appends the HTML to the article object
//$article->text .= $html;
//return;
// Return the Komento HTML code
return $html;
}
/******************************************************
*
* END
* [BASIC FUNCTIONS (METHODS)]
*
******************************************************/
}