Table of content

• HikaSerial Plugin
  • How to create an HikaSerial plugin
  • configurationHead
  • configurationLine
  • Function: listPlugins
  • Function: pluginParams
• Generator Plugin
  • generate
  • onDisplaySerials
  • onDisplaySerialForm
  • onPackGeneratorTypeDisplay
• Consumer Plugin
  • onBeforeSerialConsume
  • onAfterSerialConsume
  • onBeforeSerialCheck
  • onAfterSerialCheck
• Download Plugin
  • onBeforeSerialDownloadFile
• Subscription Plugin
  • onBeforeSubscriptionCreate
  • onAfterSubscriptionCreate
  • onBeforeSubscriptionUpdate
  • onAfterSubscriptionUpdate
  • onSubscriptionActivation
  • onSubscriptionUpgrade
  • onSubscriptionExpiration
  • onBeforeSubscriptionsExpire
  • onBeforeSubscriptionsClose
  • onAfterSubscriptionsExpire
  • onAfterSubscriptionsClose

HikaSerial Plugin

How to create an HikaSerial plugin

When you create a plugin for HikaSerial, you have to extends your plugin from hikaserialPlugin.
It would give you a good base of functions and variables. You would just have to override functions you want to customize.
You can look at existing HikaSerial plugins in the plugins/hikaserial directory, randomgen or groupconsumer are good examples !

class plgHikaserialMypluginname extends hikaserialPlugin {
	protected $type = 'generator';
	protected $multiple = true;
	protected $populate = true;
}

An HikaSerial plugin have several variables that you can override.

• $type (string): the type of the HikaSerial plugin. it could be
  • generator (default)
  • consumer
  • generic
• $multiple (boolean): generator and consumer plugin could have multiple configuration. For the random generator for example, it is possible to create different configuration.
• $populate (boolean): indicate for generator if it is possible to use the generate button in the backend. Use false if you require some information from the user, the order, etc.

These variables are protected, so it is not possible to access them from the outside. That's why some little functions exists in HikaserialPlugin:

• public function type(): return the type string
• public function isMultiple(): return the boolean value of $multiple
• public function canPopulate(): return true only if the plugin is a generator and $populate is true. Otherwise, return false.

configurationHead

This function comes in pair with "configurationLine".
It allows a plugin to add some columns in the listing so the end-user can see easily some setting without having to open each plugin instance.

/**
 * @return array : the columns to add in the header.
 */
public function configurationHead()

Example of how (and when) use it:

public function configurationHead() {
	// Add a columns for the packs
	return array(
		'packs' => array(
			'title' => JText::_('SERIAL_PACKS'),
			'cell' => 'width="30%"'
		)
	);
}

configurationLine

When you have some columns via the function "configurationHead", that functino will be called in order to fill the cell for the different instances of the plugin.

/**
 * @param int $key : the key of the column.
 * @param object $conf : the plugin instance.
 * @return string (or null) : the content for the cell.
 */
public function configurationLine($key = 0, $conf = null)

Example of how (and when) use it:

public function configurationLine($key = 0, $conf = null) {
	if(empty($this->toggleHelper))
		$this->toggleHelper = hikaserial::get('helper.toggle');
	switch($key) {
		case 'packs':
			$v = !empty($conf->plugin_params->packs) ? 1 : 0;
			return $this->toggleHelper->display('', $v);
	}
	return null;
}

listPlugins

The function would give you the list of configurations if the plugin is a generator or a consumer.
The output variable would contains the associated list or just contains the list of plugin's ids if $full is false.

/**
 * @param string $name : the name of the plugin.
 * @param array $values : output variable for getting values.
 * @param boolean $full : load full information.
 */
public function listPlugins($name, &$values, $full = true)

Example of how (and when) use it:

public function onPackGeneratorTypeDisplay(&$values) {
	// list all sub generators
	parent::listPlugins('mygeneratorplugin', $values);
}

pluginParams

This function allow you to load the plugin parameters.
When the function is called, the variable $this->plugin_params would receive the parameters. If there is an error, the function would return false and the variable would be null.

/**
 * @param int $id : the id of the hikaserial plugin
 * @return boolean : if $this->plugin_params has been loaded or not.
 */
public function pluginParams($id = 0) { return true; }

Example of how (and when) use it:

public function generate(&$pack, &$order, $quantity, &$serials) {
	if(!isset($pack->mygeneratorplugin))
		return;

	// load $this->plugin_params;
	parent::pluginParams($pack->mygeneratorplugin);
	
	/* ... */
}

Generator Plugin

Generate

The generate function is the main function for generator plugins.
The function does not have to return a value, it will create serials and add them into the "$serials" parameter.

/**
 * @param object $pack : the hikashop pack object, with the options.
 *  [ pack_id, product_id, quantity, pack_name, pack_data, pack_generator, pack_params ]
 * @param object $order : the hikashop order object, with all data.
 * @param int $quantity : the quantity of serials that you generator has to create.
 * @param array $serials : output array for the generated serials.
 */
public function generate(&$pack, &$order, $quantity, &$serials) {
	if(!isset($pack->mypluginname)) // replace "mypluginname" by your plugin name
		return;

	// load $this->plugin_params;
	parent::pluginParams($pack->mypluginname); // replace "mypluginname" by your plugin name

	for($q = 0; $q < $quantity; $q++) {
		$serial = '';
		/*
		 * Generate your serial here
		 */
		$serials[] = $serial;
	}
}

This function is not a trigger, HikaSerial would load the plugin and call directly it.
If the generator is a populate generator, this function could be called from the "generator" button in the backend. If your generator require the order to read some information about the user, other products are something else, you have to set $populate to false.

onDisplaySerials

This function allow you to override the way that your serial would be displayed.
When the function is called, the variable $this->plugin_params would receive the parameters. If there is an error, the function would return false and the variable would be null.

/**
 * @param object-list $data : the list of serials to display.
 * @param string $viewName : the current view name.
 *  - back-serial-listing
 *  - back-serial-form
 *  - order_back_show
 *  - order_front_show
 *  - email_notification_html
 */
public function onDisplaySerials(&$data, $viewName) { return; }

An example of DisplaySerial for a "Link Generator"

/**
 * @param object-list $data : the list of serials to display.
 * @param string $viewName : the current view name.
 */
public function onDisplaySerials(&$data, $viewName) {
	// Does not modify serial data in the backend form.
	if($viewName == 'back-serial-form')
		return;
	foreach($data as &$serial) {
		// Only modify serials for this generator plugin.
		if($serial->pack_generator != 'plg.mylinkgenerator')
			continue;
		// Does not generator link of the serial is empty
		if(!empty($serial->serial_data)) {
			// Create an HTML link.
			$serial->serial_data = '<a href="'.$serial->serial_data.'">'.$serial->serial_data.'</a>';
		}
	}
	return;
}

onDisplaySerialForm

If the serial have the "custom_display" set to "true", that specific trigger will be called when the serial is edited in the backend.

/**
 * @param object $serial : the serial which is being display in the backend form.
 */
public function onDisplaySerials(&$serial) { return; }

onPackGeneratorTypeDisplay

For multiple configuration plugins:

/**
 * @param array $values : the output list of generators
 */
public function onPackGeneratorTypeDisplay(&$values) {
	// list all sub generators
	parent::listPlugins('mypluginname', $values);
}

For simple generator plugin:

/**
 * @param array $values : the output list of generators
 */
public function onPackGeneratorTypeDisplay(&$values) {
	$values['plg.mypluginname'] = JText::_('MY_PLUGIN_NAME'); // Or just 'My Plugin Name' if you don't want to use translations.
}

Consumer Plugin

Consumer plugins are called before the process in order to have the right to continue.
After validation, the second trigger is called and plugins are allowed to make their process.

onBeforeSerialConsume

This trigger is called in order to ask for the "right to continue".

/**
 * @param object $serial : the serial object.
 * @param integer $user_id : the hikashop user identifier (0 is in backend of user check is not ask)
 * @param boolean $do : the return value "do" which could stop the consume process
 */
public function onBeforeSerialConsume(&$serial, $user_id, &$do) { return; }

An example of serial consummation.

/**
 * @param object $serial
 * @param integer $user_id
 * @param boolean $do
 */
public function onBeforeSerialConsume(&$serial, $user_id, &$do) {
	$user = hikaserial::loadUser(true);
	parent::pluginParams();
	if($this->plugin_params->pack_id = $serial->serial_pack_id) {
		if(empty($user) || empty($user->user_cms_id)) {
			$do = false;
		}
		return;
	}
}

onAfterSerialConsume

This trigger is called when the user just consume the serial.
The plugin can do his specific tasks, like updating values for the user, updating the order or a lot of other things.

/**
 * @param object $serial
 */
public function onAfterSerialConsume(&$serial) { return; }

An example of serial consummation.

/**
 * @param object $serial
 */
public function onAfterSerialConsume(&$serial) {
	$user = hikaserial::loadUser(true);
	$cms_id = $user->user_cms_id;
	parent::pluginParams($id);
	if($this->plugin_params->pack_id = $serial->serial_pack_id) {
		// Do something
	}
}

onBeforeSerialCheck

This trigger is called in order to ask for the "right to continue".

/**
 * @param string $serial_data : the serial that the user asked for.
 * @param boolean $do : the return value "do" which could stop the consume process
 * @param array $filters : the SQL filters which will be used in the SQL query to find the serial.
 */
public function onBeforeSerialCheck(&$serial_data, &$do, &$filters) { return; }

onAfterSerialCheck

This trigger is called when the user just check the serial.
The plugin can have a direct access to the returned content so it can hide some elements.

/**
 * @param string $serial_data : the serial that the user asked for.
 * @param object $ret : the found serial object that will be return to the user.
 */
public function onAfterSerialCheck($serial_data, &$ret) { return; }

Download Plugin

Download plugins allow you to create unique downloadable files

onBeforeSerialDownloadFile

This trigger is called when the user wants to download a file from a product with a serial.

/**
 * @param object $serial
 */
public function onBeforeSerialDownloadFile(&$filename, &$do, &$file, &$serials) { return; }

Subscriptions Plugin

subscriptions plugins allow you to interact with the modifications in subscriptions

onBeforeSubscriptionCreate

/**
 * @param object $subscription : the subscription object that being create.
 * @param boolean $do : the return value "do" which could stop the creation process
 */
public function onBeforeSubscriptionCreate(&$subscription, &$do) { return; }

onAfterSubscriptionCreate

/**
 * @param object $subscription : the subscription object that being create.
 * @param int $status : the subscription_id or 0 if the creation failed
 */
public function onAfterSubscriptionCreate(&$subscription, $status) { return; }

onBeforeSubscriptionUpdate

/**
 * @param object $subscription : the subscription object that being update.
 * @param boolean $do : the return value "do" which could stop the update process
 */
public function onBeforeSubscriptionUpdate(&$subscription, &$do) { return; }

onAfterSubscriptionUpdate

/**
 * @param object $subscription : the subscription object that being update.
 * @param int $status : the subscription_id or 0 if the update failed
 */
public function onAfterSubscriptionUpdate(&$subscription, $status) { return; }

onSubscriptionActivation

/**
 * @param object $subscription : the subscription object that being update.
 * @param object $user : 
 */
public function onSubscriptionActivation(&$subscription, $user) { return; }

onSubscriptionUpgrade

/**
 * @param object $subscription : the subscription object that being update.
 * @param object $user : 
 */
public function onSubscriptionUpgrade(&$subscription, $user) { return; }

onSubscriptionExpiration

/**
 * @param object $subscription : the subscription object that being update.
 * @param object $user : 
 * @param string $subscription_status : 
 */
public function onSubscriptionExpiration(&$subscription, $user, $subscription_status) { return; }

onBeforeSubscriptionsExpire

/**
 * @param array $expired_subscriptions : the subscriptions in expiration
 * @param array $plans : the plans related to the expired subscriptions
 * @param array $users : the users related to the expired subscriptions
 */
public function onBeforeSubscriptionsExpire(&$expired_subscriptions, $plans, $users) { return; }

onBeforeSubscriptionsClose

/**
 * @param array $closed_subscriptions : the subscriptions in closure
 * @param array $plans : the plans related to the closed subscriptions
 * @param array $users : the users related to the closed subscriptions
 */
public function onBeforeSubscriptionsClose(&$closed_subscriptions, $plans, $users) { return; }

onAfterSubscriptionsExpire

/**
 * @param array $expired_subscriptions : the subscriptions in expiration
 * @param array $plans : the plans related to the expired subscriptions
 * @param array $users : the users related to the expired subscriptions
 */
public function onAfterSubscriptionsExpire(&$expired_subscriptions, $plans, $users) { return; }

onAfterSubscriptionsClose

/**
 * @param array $closed_subscriptions : the subscriptions in closure
 * @param array $plans : the plans related to the closed subscriptions
 * @param array $users : the users related to the closed subscriptions
 */
public function onAfterSubscriptionsClose(&$closed_subscriptions, $plans, $users) { return; }