Plugin Files

Front-end plugin files

Plugin initialization file "myplugin_init.php"

Front-end initialization file example syntax:

<?php  
/* Frontend initialization file example syntax: */
/* Very important */
defined( '_VALID_MOS' ) or die( 'Restricted access' );
 
global $config;
/* here a language file can be included */
if (file_exists("{$config->S2_pluginsPath}/myplugin/{$config->sobi2Language}.php"))
{
  require_once("{$config->S2_pluginsPath}/myplugin/{$config->sobi2Language}.php" );
}
else {
    require_once("{$config->S2_pluginsPath}/myplugin/english.php" );
}
 
/* include class definition */
require_once("{$config->S2_pluginsPath}/myplugin/myplugin.class.php");
 
/* create an object */
$sobi_myplugin = new sobi_myplugin();
/* put the object to the plugins array */
/* $plugin->name_id is defined in sobi2.php */
$config->S2_plugins[$plugin->name_id] = $sobi_myplugin;
?>

Plugin class definition file "myplugin.class.php"

The plugin object has to define the following methods and attributes:

Attributes:

string $name - in front-end displayed name of the plugin. Can be null.
string $listingStyle - CSS class name for displaying the plugin in the category view. Can be null.

Methods:

void onSobiStart ()

Function which will be executed after start of SOBI2 component.

boolean customTask (string $sobi2Task)

Gets sobi2Task as argument.

Function to execute different operations. This method is called every time a sobi2Task doesn't belong to any SOBI2 actions. That means, if SOBI2 is called for example like "index2.php?option=com_sobi2&sobi2Task=top_rated", SOBI2 will ask all plugins if they have an action for the task "top_rated". If your plugin has an action for this task, it has to return "true" in this case.

Example:

function customTask($sobi2Task) {
    switch($sobi2Task) {
    case "top_rated":
      doSomething();
      $ret = true;
      break;
    default:
      $ret = false;
      break;
  }
  return $ret;
}

void Main ()

(Deprecated, use customTask() instead)

Function to execute different operations. This method is called every time like this "index2.php?option=com_sobi2&sobi2Task=pluginMain&S_plugin=myplugin&..."

string showDetails (string $sobi2Id)

Gets id of the entry as argument.

Will be called in details view. Has to return what you want to display as a string. If you don't want to show anything there, this function should return null.

string showListing (int $sobi2Id)

Gets id of the entry as argument.

Will be called in category view. Has to return what you want to display as a string. If you don't want to show anything there, this function should return null.

string editForm (string $sobi2Id)

Gets id of the entry as argument.

Will be called in the new/edit entry function within the existing form. Has to return what you want to display as a string. If you don't need to show anything there, this function should return null.

array save (array $input, int $sobi2Id)
array update (array $input, int $sobi2Id)

These both functions are identical. But the first will be called on saving a new entry, and the second on updating (edit) an entry. The first argument is an array with two fields:

array $input['msg']
Gets the message which will be displayed after saving/updating. You can add your own message or change it.
array $input['fees']

Contains the array with selected non free options. You can add something to this array if your plugin provides also some non free options like this:

$input['fees'] += array("Fees for myplugin option" => 10);

This function has always to return the $input array, even if your plugin doesn't use it.

void onSearchStart (string &$searchString, string &$phrase, array &$dropListsArray)

This method will be executed after the user starts the search function. In this moment the drop down boxes are already created.

string &$searchString
Reference to the string to search. If the search function has started at first time, this string is empty.
string &$phrase
Reference to the phrase. The part of search function which said "Search For All" or "Search For Any" or "Search For Exact"
array &$dropListsArray
Reference to the array with all drop down boxes. This array is build like this $dropListsArray[label to display] => mosHTML::selectList

void onSearchResult (array &$items, array &$dataForFields, string &$pluginsOutput)

This method will be executed after the search has been executed and before the results are displayed. So this function allows to modify the search results.

array &$items
Reference to the array with all found entries using the basic SOBI2 search function. Here you can add own results, or remove some others.
array &$dataForFields
Reference to the array with selected options for the drop down boxes. All values within this array will be added to the url for the page navigation. So if you want to transfer some values to the next search page, you should add them to this array. This array is build up like the $dataForFields[name] => value.
string &$pluginsOutput
Reference to string with custom plugin output.

void onPaymentScreen ()

This function will be executed on the payment screen if the user chooses some not free options. The output will be shown after the "Bank Transfer" and "PayPal" payment methods.

void onPaymentMailUser (string &$mailTitle, string &$mailMsg, string &$email)

This function can modify the content of the payment email to the user.

string &$mailTitle
Reference to email title
string &$mailMsg
Reference to email content
string &$email
Reference to email address of the user

void onPaymentMailAdmin (string &$AdmMailTitle, string &$AdmMailMsg, 
         string &$AdmEmail, string &$AdmEmail)

This function can modify the content of the payment email to the admin.

string &$AdmMailTitle
Reference to email title
string &$AdmMailMsg
Reference to email content
string &$AdmEmail
Reference to email address of the admin

string replaceMarkers (string $string)

This function will be called every time before an email will be send. Gets the string with the email template as argument. You can search for and replace your self defined place holders. This function has always to return the string with the template, even if your plugin doesn't use it.

Back-end plugin files

Plugin initialization file "admin.myplugin_init.php"

Backend initialization file example syntax:

<?php
/* Backend initialization file example syntax: */
/* Very important */
defined( '_VALID_MOS' ) or die( 'Restricted access' );
 
global $config;
/* include class definition */
require_once("{$config->S2_pluginsAdmPath}/myplugin/admin.myplugin.class.php");
 
/* here a language file can be included */
if (file_exists("{$config->S2_pluginsPath}/myplugin/{$config->sobi2Language}.php")) 
{
  require_once("{$config->S2_pluginsPath}/myplugin/{$config->sobi2Language}.php" );
}
else {
   require_once("{$config->S2_pluginsPath}/myplugin/english.php" );
}
  
/* create an object */
$sobi_myplugin_adm = new sobi_myplugin_adm();
/* put the object to the plugins array */
/* $plugin->name_id is defined in admin.sobi2.php */
$config->S2_plugins[$plugin->name_id] = $sobi_myplugin_adm;
?>

Plugin class definition file "admin.myplugin.class.php"

The plugin object has to define the same methods and attributes like the front-end object so it is good idea that the back-end class is derived from the front-end class (extends the class). Additionally this object has to define the following methods:

void config ()

This function should display inline the configuration menu for the plugin. It will be displayed whthin a "<form>" tag, so you don't have to care about it. Also the save button will be shown. After click on the "save" button the function saveConfig() will be called.

void saveConfig ()

This function should be used to save the configuration settings of the plugin.

Installation Files

XML installation file "myplugin.xml"

File example syntax:

<?xml version="1.0" encoding="UTF-8"?>
<sobi2plugin>
<!-- Few standard information -->
<name>myplugin</name>
<nameId>myplugin_id</nameId>
<description>description of myplugin</description>
<author>You</author>
<authorEmail>info[at]server.com</authorEmail>
<authorUrl>www.server.com</authorUrl>
<creationDate>October 2006</creationDate>
<copyright>(C) 2006 You</copyright>
<license>www.gnu.org/copyleft/gpl.html GNU/GPL</license>
<version>Version Number</version>
 
<!-- Name of initialization file for backend -->
<initFile>myplugin_init.php</initFile>
<!-- All files you want to copy -->  
<!-- Please take notice: 
through the XML installer file, files are copied only to the root.
It will not create any sub directories. If you need to have sub directories 
you have to use the install.php file to create them -->
<files>
<frontend>
<file>myplugin.class.php</file>
<file>myplugin_init.php</file>
<file>file.js</file>
<file>myplugin.css</file>
<file>germani.php</file>
<file>germanf.php</file>
<file>english.php</file>
</frontend>
<backend>
<file>admin.myplugin.class.php</file>
<file>admin.myplugin_init.php</file>
<file>install.php</file>
</backend>
</files>
 
<!-- Database queries -->
<queries>
<!-- The name `#__myplugin` will be replaced with something like 
`jos_sobi2_plugin_myplugin` -->
 
<query table="myplugin">
CREATE TABLE `#__myplugin` (
`id` int(11) NOT NULL AUTO_INCREMENT,
`itemid` int(11) NOT NULL default '0',
`something` varchar(30) default NULL,
`somethingElse` varchar(30) default NULL,
PRIMARY KEY (`imgid`));
</query>
<query>INSERT IGNORE INTO 
    `#__sobi2_config` VALUES ('something', '1', 'myplugin', NULL);</query>
<query>INSERT IGNORE INTO 
    `#__sobi2_config` VALUES ('somethingElse', '10', 'myplugin', NULL);</query>
</queries>
</sobi2plugin>

PHP installation file "install.php"

This file will be called (if exists) at last of the installation process. It could be used for some additional operations, like copying some files, creating directories or something else.

Package File

The package file has to be a ZIP file. It has to be named exactly as the XML file (myplugin.xml, myplugin.zip). All files within the package are always extracted to the directory: /administrator/components/com_sobi2/includes/install/myplugin/