Hook System

Hook System Overview

From SVN version 741 (yet to be released as an official version) FOG has the ability to be "hooked" and extended using an Object Orientated approach.

Events are called throughout FOG, allowing developers to hook into FOG at certain code points without editing FOG's base code.

Right now the Event list gives you the ability modify Data and Styling on all Management Search & List pages.

Keep in mind that this code is still experimental and may change at any time.

Critical Files

lib/fog/Hook.class.php
lib/fog/HookManager.class.php
lib/hooks/*.hook.php

Hook Class Variables & Methods

Variables

class ExampleHook extends Hook
{
	// Required
	var $name = 'string';
	var $description = 'string';
	var $author = 'string';


	// Optional with defaults
	var $active = true;
	var $logLevel = 0;
	var $logToFile = false;
	var $logToBrowser = true;
}

Inherited Methods

Methods that are available within your Hook Class

Function: void log( string $txt [, int $level = 1] )
Example: $this->log('Debug alert !! Run for the hills !!');

Function: bool isAJAXRequest()
Example: if (!$this->isAJAXRequest()) print_r($debug);

Enabling / Disabling Hooks

Hooks can be enabled and disabled by changing the variable $active inside of the class you wish to enable / disable;

To Enable:

var $active = true;

To Disable:

var $active = false;

How to Hook Events

Hook Events are called in various parts of the FOG code. Hooking these Events is very simple.

Example for Event: HostData

$ExampleHook = new ExampleHook();
$HookManager->register('HostData', array($ExampleHook, 'HostData'));  // This will call the function HostData( array $arguments ) in $ExampleHook

A full list of Events can be found here: http://www.fogproject.org/wiki/index.php?title=Hook_System#Events

Function Arguments

When an Event Hook is fired, various arguments are passed to the function specified. These arguments may vary.

Returned argument indexes

'event' : Always returned. Returns the name of the event fired to get here

'data' : Contains data variables used to replace %name% strings in 'templates'

'templates' : Each index will become a new column. Using %name% variables will be converted to the matching key index in 'data'

'attributes' : Array of attributes to apply to each column wrapper. i.e. class, width, height, style

Example

Here is an example showing the data passed from the HostData Event

Code

function run($arguments)
{
	$this->log(print_r($arguments, 1));
}

Output

Array
(
	[event] => 'HostData'
	[data] => Array
	(
		[0] => Array
		(
			[id] => '968'
			[hostname] => '12583-M780'
			[mac] => '00:23:18:ef:b4:8d'
		)
		[1] => Array
		(
			[id] => '966'
			[hostname] => '12700-M780'
			[mac] => '00:23:18:72:50:8d'
		) 
		[2] => Array
		(
			[id] => '1011'
			[hostname] => '12703-M780'
			[mac] => '00:23:18:97:a8:8d'
		)
		[3] => Array
		(
			[id] => '1251'
			[hostname] => '12705-M780'
			[mac] => '00:23:18:60:26:96'
		)
	)
	[templates] => Array
	(
		[0] => '<input type="checkbox" name="HID%id%" checked="checked" />'
		[1] => '<span class="icon ping"></span>'
		[2] => '<a href="?node=host&sub=edit&id=%id%" title="Edit">%hostname%</a>'
		[3] => '%mac%'
		[4] => '%ip%'
		[5] => '<a href="?node=host&sub=edit&id=%id%"><span class="icon icon-edit" title="Edit: %hostname%"></span></a>'
	)
	[attributes] => Array
	(
		[0] => Array ( )
		[1] => Array ( )
		[2] => Array ( )
		[3] => Array ( )
		[4] => Array ( )
		[5] => Array ( ['class'] => 'c' )
	)
)

Hook Template

This is the most basic hook template
Your hook MUST extend the FOG Hook Class 'Hook' otherwise HookManager will fail to Hook the Event

Location: lib/hooks/Template.hook.php

<?php
/****************************************************
 * FOG Hook: Template
 *	Author:		Blackout
 *	Created:	8:57 AM 31/08/2011
 *	Revision:	$Revision: 743 $
 *	Last Update:	$LastChangedDate: 2011-09-04 11:50:55 +1000 (Sun, 04 Sep 2011) $
 ***/

// Hook Template
class HookTemplate extends Hook
{
	var $name = 'Hook Name';
	var $description = 'Hook Description';
	var $author = 'Hook Author';
	
	var $active = false;
	
	function HostData($arguments)
	{
		$this->log(print_r($arguments, 1));
	}
}

// Init class
$HookTemplate = new HookTemplate();

// Hook Event
$HookManager->register('HostData', array($HookTemplate, 'HostData'));

Events

Hook Events allow you to jump into the FOG code at a certain point. When an event is fired, data and styling information related to that event can be made available to the Hook Developer for modification.

Adding hooking points can be a time consuming process as the HTML, Data and Styling needs to be (re-)written in a particular way to allow hooking.

More events will be added. If you require a particular hooking point, please contact Blackout with where the Hook needs to be made and any code you have developed :)

// Global
CSS
JavaScript
MainMenuData				// data => array
SubMenuData				// FOGSubMenu => FOGSubMenu Object
MessageBox				// data => string

// Host Management
// List / Search
HostTableHeader
HostData
HostAfterTable
// Edit
HostEditUpdate				// host => Host Object
HostEditUpdateSuccess			// host => Host Object
HostEditUpdateFail			// host => Host Object
HostEditConfirmMACUpdate		// host => Host Object
HostEditConfirmMACUpdateSuccess		// host => Host Object, mac = MACAddress Object
HostEditConfirmMACUpdateFail		// host => Host Object, mac = MACAddress Object
HostEditADUpdate
HostEditADUpdateSuccess
HostEditADUpdateFail
HostEditAddSnapinUpdate
HostEditAddSnapinUpdateSuccess
HostEditAddSnapinUpdateFail
HostEditRemoveSnapinUpdate
HostEditRemoveSnapinUpdateSuccess
HostEditRemoveSnapinUpdateFail

// Group Management
GroupTableHeader
GroupData
GroupAfterTable

// Image Management
ImageTableHeader
ImageData
ImageAfterTable

// Storage Node Management
// All Storage Nodes
StorageGroupTableHeader
StorageGroupData
StorageGroupAfterTable
// All Storage Groups
StorageNodeTableHeader
StorageNodeData
StorageNodeAfterTable

// Snapin Management
SnapinTableHeader
SnapinData
SnapinAfterTable

// Printer Management
PrinterTableHeader
PrinterData
PrinterAfterTable

// Task Management
// Active Tasks
TasksActiveTableHeader
TasksActiveData
TasksActiveAfterTable
TasksActiveRemove
TasksActiveRemoveSuccess
TasksActiveRemoveFail
TasksActiveForce
TasksActiveForceSuccess
TasksActiveForceFail
// Search
TaskData
TasksSearchTableHeader
// List Hosts
TasksListHostTableHeader
TasksListHostData
TasksListHostAfterTable
// List Group
TasksListGroupTableHeader
TasksListGroupData
TasksListGroupAfterTable
// Scheduled Tasks
TasksScheduledTableHeader
TasksScheduledData
TasksScheduledAfterTable
TasksScheduledRemove
TasksScheduledRemoveSuccess
TasksScheduledRemoveFail
// Active Multicast Tasks
TasksActiveMulticastTableHeader
TasksActiveMulticastData
TasksActiveMulticastAfterTable
// Active Snapins
TasksActiveSnapinsTableHeader
TasksActiveSnapinsData
TasksActiveSnapinsAfterTable
TasksActiveSnapinsRemove			// id => snapinID, hostID => hostID
TasksActiveSnapinsRemoveSuccess			// id => snapinID, hostID => hostID
TasksActiveSnapinsRemoveFail			// id => snapinID, hostID => hostID

// Login
Login						// username => string, password => string
LoginSuccess					// username => string, password => string, user => User Object
LoginFail					// username => string, password => string

// Logout
Logout

Up to date as of SVN r759

Examples

HostVNCLink

Adds a "VNC" link to the Host Lists

Location: lib/hooks/HostVNCLink.hook.php

<?php
/****************************************************
 * FOG Hook: HostVNCLink
 *	Author:		Blackout
 *	Created:	9:26 AM 3/09/2011
 *	Revision:	$Revision: 743 $
 *	Last Update:	$LastChangedDate: 2011-09-04 11:50:55 +1000 (Sun, 04 Sep 2011) $
 ***/

// HostVNCLink - custom hook class
class HostVNCLink extends Hook
{
	// Class variables
	var $name = 'HostVNCLink';
	var $description = 'Adds a "VNC" link to the Host Lists';
	var $author = 'Blackout';
	
	var $active = false;
	
	// Custom variable
	var $port = 5800;
	
	function HostData($arguments)
	{
		// Add column template into 'templates' array
		$arguments['templates'][] = sprintf('<a href="http://%s:%d" target="_blank">VNC</a>', '%hostname%', $this->port);
		// Add these HTML attributes to that column
		$arguments['attributes'][] = array('class' => 'c');
	}
	
	function HostTableHeader($arguments)
	{
		// Add new Header column with the content 'VNC'
		$arguments['templates'][] = 'VNC';
		// Add these HTML attributes to that column
		$arguments['attributes'][] = array('width' => '40', 'class' => 'c');
	}
}

// Init
$HostVNCLink = new HostVNCLink();

// Register hooks with HookManager on desired events
$HookManager->register('HostData', array($HostVNCLink, 'HostData'));
$HookManager->register('HostTableHeader', array($HostVNCLink, 'HostTableHeader'));

RemoveIPAddressColumn

Removes the "IP Address" column from Host Lists

Location: lib/hooks/RemoveIPAddressColumn.hook.php

<?php
/****************************************************
 * FOG Hook: Remove 'IP Address' column
 *	Author:		Blackout
 *	Created:	1:52 PM 3/09/2011
 *	Revision:	$Revision: 743 $
 *	Last Update:	$LastChangedDate: 2011-09-04 11:50:55 +1000 (Sun, 04 Sep 2011) $
 ***/

// RemoveIPAddressColumn class
class RemoveIPAddressColumn extends Hook
{
	var $name = 'RemoveIPAddressColumn';
	var $description = 'Removes the "IP Address" column from Host Lists';
	var $author = 'Blackout';
	
	var $active = false;
	
	function HostTableHeader($arguments)
	{
		// Remove IP Address column by removing its column template
		unset($arguments['templates'][4]);
	}
	
	function HostData($arguments)
	{
		// Remove IP Address column by removing its column template
		unset($arguments['templates'][4]);
	}
}

// Init
$RemoveIPAddressColumn = new RemoveIPAddressColumn();

// Register hooks
$HookManager->register('HostTableHeader', array($RemoveIPAddressColumn, 'HostTableHeader'));
$HookManager->register('HostData', array($RemoveIPAddressColumn, 'HostData'));

Example.ChangeTableHeader

Remove & add table header columns

Location: lib/hooks/Example.ChangeTableHeader.hook.php

<?php
/****************************************************
 * FOG Hook: Example Change Table Header
 *	Author:		Blackout
 *	Created:	8:57 AM 31/08/2011
 *	Revision:	$Revision: 743 $
 *	Last Update:	$LastChangedDate: 2011-09-04 11:50:55 +1000 (Sun, 04 Sep 2011) $
 ***/

// Example class
class TestHookChangeTableHeader extends Hook
{
	var $name = 'ChangeTableHeader';
	var $description = 'Remove & add table header columns';
	var $author = 'Blackout';
	
	var $active = false;
	
	function HostTableHeader($arguments)
	{
		// DEBUG output
		foreach ($arguments['templates'] AS $i => $data)
		{
			$this->log(sprintf('Table Rows: i: %s Data: %s', $i, print_r($data, 1)));
		}
		
		// Rename column 'Host Name' -> 'Chicken Sandwiches'
		$arguments['templates'][2] = 'Chicken Sandwiches';
		
		// Override column values & attributes
		$arguments['templates'][5] = 'Edit Me !!';
		$arguments['attributes'][5] = array('width' => '40', 'class' => 'c');
	}
}

// Example: Change Table Header and Data
$HookManager->register('HostTableHeader', array(new TestHookChangeTableHeader(), 'HostTableHeader'));

Example.ChangeData

Appends "Chicken-" to all hostnames

Location: lib/hooks/Example.ChangeData.hook.php

<?php
/****************************************************
 * FOG Hook: Example Change Hostname
 *	Author:		Blackout
 *	Created:	8:57 AM 31/08/2011
 *	Revision:	$Revision: 743 $
 *	Last Update:	$LastChangedDate: 2011-09-04 11:50:55 +1000 (Sun, 04 Sep 2011) $
 ***/

// Example class
class TestHookChangeHostname extends Hook
{
	var $name = 'ChangeHostname';
	var $description = 'Appends "Chicken-" to all hostnames ';
	var $author = 'Blackout';
	
	var $active = false;
	
	function HostData($arguments)
	{
		foreach ($arguments['data'] AS $i => $data)
		{
			// DEBUG
			//$this->log(sprintf('Renaming Host: i: %s Data: %s', $i, print_r($data, 1)));
			
			// Rename host
			$arguments['data'][$i]['hostname'] = 'Chicken-' . $data['hostname'];
		}
	}
}

// Example: Test by changing all hostnames in Host Management
$HookManager->register('HostData', array(new TestHookChangeHostname(), 'HostData'));

Example.SideMenuChange

Example showing how to manipulate SubMenu Data. Adds Menu items under "Host Management"

Location: lib/hooks/Example.SideMenuChange.hook.php

<?php
/****************************************************
 * FOG Hook: Example.SideMenuChange
 *	Author:		Blackout
 *	Created:	12:10 PM 4/09/2011
 *	Revision:	$Revision: 743 $
 *	Last Update:	$LastChangedDate: 2011-09-04 11:50:55 +1000 (Sun, 04 Sep 2011) $
 ***/

// Hook Template
class HookSubMenuData extends Hook
{
	var $name = 'SubMenuData';
	var $description = 'Example showing how to manipulate SubMenu Data. Adds Menu items under "Host Management"';
	var $author = 'Blackout';
	
	var $active = false;
	
	function SubMenuData($arguments)
	{
		if ($GLOBALS['node'] == 'host')
		{
			// Add a new item under 'Host Management'
			$arguments['FOGSubMenu']->addItems('host', array(_('New Hook Item') => 'http://www.google.com', _('New Hook Item 2') => "newhookitem2"));
			
			if ($GLOBALS['id'])
			{
				// Add a new item under 'Host Management' per Host
				$arguments['FOGSubMenu']->addItems('host', array(_('New Hook Item') => "http://www.google.com", _('New Hook Item 2') => "newhookitem2"), 'id', $GLOBALS['hostname']);
			}
		}
	}
}

// Init class
$HookSubMenuData = new HookSubMenuData();

// Hook Event
$HookManager->register('SubMenuData', array($HookSubMenuData, 'SubMenuData'));

Debugging

Using the 'Hook Debugger' hook, you can debug all hook events to browser and/or log file

Location: lib/hooks/HookDebugger.hook.php

You must enable this hook See: http://www.fogproject.org/wiki/index.php?title=Hook_System#Enabling_.2F_Disabling_Hooks

<?php
/****************************************************
 * FOG Hook: HookDebugger
 *	Author:		Blackout
 *	Created:	8:57 AM 31/08/2011
 *	Revision:	$Revision: 744 $
 *	Last Update:	$LastChangedDate: 2011-09-04 12:02:48 +1000 (Sun, 04 Sep 2011) $
 ***/

// HookDebugger class
class HookDebugger extends Hook
{
	var $name = 'HookDebugger';
	var $description = 'Prints all Hook data to the web page and/or file when a hook is encountered';
	var $author = 'Blackout';
	
	var $active = false;
	
	var $logLevel = 9;
	var $logToFile = false;		// Logs to: lib/hooks/HookDebugger.log
	var $logToBrowser = true;
	
	function run($arguments)
	{
		$this->log(print_r($arguments, 1));
	}
}

// Debug all events
$HookDebugger = new HookDebugger();
foreach ($HookManager->events AS $event)
{
	$HookManager->register($event, array($HookDebugger, 'run'));
}

Hook System

Contents

Hook System Overview

Critical Files

Hook Class Variables & Methods

Enabling / Disabling Hooks

How to Hook Events

Function Arguments

Hook Template

Events

Examples

Debugging

Navigation menu

Personal tools

Namespaces

Variants

Views

More

Search

Navigation

Documentation

FAQs / Troubleshooting

Other Information

Special Tools

Tools