/*
	This is a sample hook class with every vbulletin code hook defined.
*/
class sample_Hooks
{
	/*
		This determines the order the class is called.  If it is not defined then
		default of 10 will be used.  The class with the lowest value will be
		invoked first if multiple classes define an implementation for the
		same hook.
	*/
	public static $order = 10;


	/*
		This hook is called when rendering the "External Connections" field
		in the AdminCP's user edit/profile page.
	*/
	public static function hookAdminCPUserExternalConnections($params)
	{
		// ID of the user being edited/displayed
		$params['userid'];

		// Nested array of external connections to display.
		$params['externalConnections'];
		// By default the following facebook array is populated:
		/*
		$params['externalConnections'][0] = array(
			'titlephrase' => 'facebook_connected',
			'connected' => !empty($user['fbuserid']),
			'helpname' => 'facebookconnect',
			'displayorder' => 10,
		);
		*/
		// Each subarray should look like above, where lower value of displayorder will
		// show on the list first.

		$params['externalConnections'][] = array(
			'titlephrase' => '',  // String phrase varname to display
			'connected' => false, // Bool Controls what's displayed. True = "Yes", false = "No"
			'helpname' => '',     // String varname for adminCP help link.
			'displayorder' => 20, // Integer. Ex. Lower than 10 will show before facebook, higher will show after.
		);
	}

	public static function hookAdminSettingsSelectOptions($params)
	{
		//the id of the setting being displayed.
		//this parameter is read only
		$params['settingid'];

		//the exact type of the select list.  Currently the values supported are:
		//* checkbox:json_array
		//* select:piped
		//* select:eval
		//* multiselect:eval
		//there are some specialized select options for user groups and other
		//system features that are not yet included
		//this parameter is read only
		$params['optioncode'];

		//the options that will be displayed in the settings screen.  They are
		//of the form "value" => "display text".
		//this parameter is editable
		$params['options'];

		//standard use case is
		if($params['settingid'] == 'someselectsetting')
		{
			$params['options']['mynewoption'] = 'My New Option Text';
		}
	}

	public static function hookAdminClearedCache($params)
	{
		/*
			This hooks is called when the admin explicitly clears the cache
			in the admincp
		*/

		//this hook does not have any parameters
	}

	/*
		This hook is called immediately after the output is generated but before
		it is displayed.  This does not include the preheader portion (which may
		already have been sent to the browser at this point depending on
		configuration).
	*/
	public static function hookFrontendBeforeOutput($params)
	{
		//the style used to render the page
		//this parameter is read only
		$params['styleid'];

		//html from the end of the preheader to the end of the page
		//this include the the entire <body> tag
		//this parameter is editable
		$params['pageHtml'];
	}


	/*
		This is called after the preheader is generated but before it is output to
		the browser.
	*/
	public static function hookFrontendPreheader($params)
	{
		//html from start of page to end of preheader
		//this parameter is editable
		$params['preheaderHtml'];
	}

	public static function hookFrontendContentBeforeAdd($params)
	{
		//editable parameter.  Will be passed as an empty string (though if there are multiple
		//implemented, a prior one could change that).  Set this to something else to
		//skip the add.  The value set will be returned instead.
		$params['altreturn']

		//to return an array use
		//$params['altreturn'] = array('errors' => array(array('phraseid_id', $param1, $param2)));

		//The string value for the apilibrary being used to add the content.
		//this is read only.
		$params['apilib'];

		//the data array being passed to the add function
		//this parameter is editable
		$params['data'];

		//the options array being passed to the add function
		//this parameter is editable
		$params['options'];
	}

	public static function hookFrontendContentAfterAdd($params)
	{
		//whether or not the add succeeded. Read only.
		$params['success'];

		//the output that will be returned to the browser.  Read only.
		$params['output'];

		//the id of the node just added. Can be used to fetch the node
		//content and perform additional actions based on the node
		//just added.
		$params['nodeid'];
	}


	public static function hookFrontendContentBeforeUpdate($params)
	{
		//editable parameter.  Will be passed as an empty string (though if there are multiple
		//implemented, a prior one could change that).  Set this to something else to
		//skip the update.  The value set will be returned instead.
		$params['altreturn']

		//to return an array use
		//$params['altreturn'] = array('errors' => array(array('phraseid_id', $param1, $param2)));

		//The string value for the apilibrary being used to add the content.
		//this is read only.
		$params['apilib'];

		//the node being edited
		//this is read only.
		$params['nodeid'];

		//the data array being passed to the update function
		//this parameter is editable
		$params['data'];

	}

	public static function hookFrontendContentAfterUpdate($params)
	{
		//The results of the update call. Read only.
		$params['updateResult'];

		//The string value for the apilibrary being used to add the content.
		//this is read only.
		$params['apilib'];

		//the id of the node just updated. Can be used to fetch the node
		//content and perform additional actions based on the node
		//just added.
		$params['nodeid'];
	}


	/*
		This is called when processing a 404 error vBulletin fails to
		recognize a url.  It triggers in the error handler.
	*/
	public static function hookFrontendOn404($params)
	{
		//read only.  The path used by the router that failed to match a vbulletin page
		$params['path'];

		//read/write paramerater.  Set to false to signal that the hook has handled
		//the 404 error and the normal application response isn't desired.
		$params['normalErrorResponse'];
	}

	/*
		This is called after a successful save of a user.
	*/
	public static function hookUserAfterSave($params)
	{
		//all parameters are read only.
		//the user id of the user
		$params['userid'];

		//if the save is being done as an administrative function
		$params['adminoverride'];

		//is this a new user?
		$params['newuser'];

		//does this user require email verification before registration is considered
		//complete (note this may be false even if activation is required if the
		//activation is skipped such as when a user is created in the admincp).
		$params['emailVerificationRequired'];

		//does the user require moderation before registration is considered
		//complete?
		$params['userIsModerated'];
	}


	/*
		This is called before a successful activation action.  This includes when
		user is placed in the moderation queue or when an existing user is
		required to reactivate due to a change in email.
	*/
	public static function hookUserAfterActivation($params)
	{
		//all parameters are read only.

		//the user id of the user
		$params['userid'];

		//is this a new user or a reactivation?
		$params['newuser'];

		//does the user require moderation before registration is considered
		//complete?
		$params['userIsModerated'];
	}


	/*
		This is called after a user is approved in the user moderation page
		of the admincp
	*/
	public static function hookUserModerationApproved($params)
	{
		//the user id of the user
		//this parameter is read only
		$params['userid'];
	}


	/*
		This is called when a user is logged in (front end, or control panel)
	*/
	public static function hookProcessNewLogin($params)
	{
		// The function results array:
		//	sessionhash -- hash identifying the new session
		//	cpsessionhash -- the hash for the cp session (only present if the user is an admin or a mod)
		//	userid -- id of the user newly logged in
		//	password -- remember me token
		//	lastvisit -- the newly logged in user's last visit,
		//	lastactivity -- the newly logged in user's last activity
		$params['result']; // Editable

		// The login type
		$params['logintype'];

		// Parameter will always be blank
		// will be removed in a future version of vb.
		$params['cssprefs'];

		// The userinfo array for the user logged in
		$params['userinfo'];
	}


	/*
		This is called when a user logs out (of the front end only, atm).
	*/
	public static function hookProcessLogout($params)
	{
		// The function results array:
		//	sessionhash -- hash identifying the new session
		//	apiaccesstoken -- the current api access token, if this is a request through MAPI

		$params['result']; // Editable

		// The userinfo array for the user logging out
		$params['userinfo'];
	}


	/*
		Called by every page when the router initializes
	*/
	public static function hookSetRouteWhitelist($params)
	{
		/*
			The whitelisted routes, available even when the forum is turned off.
			When the forum is turned off and a non-whitelisted-route is accessed,
			it will not process and display an error page instead.

			Default whitelist:
			'admincp',
			'auth/login',
		 */
		$params['whitelistRoute']; // Editable

		// e.g. add lorem/ipsum to the whitelist without modifying the others:
		$params['whitelistRoute'][] = 'lorem/ipsum';
	}


	/*
		Called by every page as the router decides on what route to use.
	*/
	public static function hookGetRouteMain($params)
	{
		// The pathInfo passed into the getRoute() function
		$params['pathInfo'];

		// The queryString passed into the getRoute() function
		$params['queryString'];

		// The anchor passed into the getRoute() function
		$params['anchor'];

		// The selected route object
		$params['route']; // Editable
	}


	/*
		Called by every page after the router decides on what route to use.
	*/
	public static function hookGetRoutingControllerActionWhitelist($params)
	{
		/*
			When the forum is turned off and a non-whitelisted-controller+action is accessed,
			the forum will display an error page.

			The whitelist should be in the form of
			{controller} => array({action1}, {action2}, ...)
			all in lowercase (not camelCase!).
			e.g.
			$params['whitelist']["googlelogin.page"] = array(
				'index',
				'json',
				'debug',
			);
		 */
		$params['whitelist']; // Editable
	}


	/*
		Called by the page controller just after the page is generated.
	*/
	public static function hookGetPageMain($params)
	{
		// The pageid of the page being generated
		$params['pageid'];

		// The user action passed to the page controller
		$params['useraction'];

		// The generated page
		$params['page']; // Editable

		// The pagekey for the generated page
		$params['pagekey']; // Editable

		// The page arguments passed to the page controller
		$params['arguments']; // Editable
	}


	/*
		Called by the registration code just before the new user is created.
	*/
	public static function hookRegistrationBeforeSave($params)
	{
		// A copy of the parent controller object
		$params['this'];

		// The registration data that is used to create the new user
		$params['data'];

		// If set to 'true', the parent registration function will be aborted without further processing
		// If set to a standard error array then the array will be returned and displayed to the user
		// The error array format is 
		$params['abort'] = ['errors' => [$phrase1, $phrase2]];

		//phrases can either be a string or an array with the phrase name and parameters, for instance
		$params['abort'] = ['errors' => [['error_x', 'some unphrased error message']]];
		//or
		$params['abort'] = ['errors' => ['my_custom_phrase_without_params']];

		$params['abort']; // Editable
	}

	/*
		Called when checking if Third party login buttons should be displayed on the login iframe.
		Use this hook if your product cannot extend the vB_Api_ExternalLogin::showExternalLoginButton()
		function
	*/
	public static function hookShowExternalLoginButton($params)
	{
		// array of {string productid} => {bool show button}.
		$params['buttons'];
		// By default, populated with facebook button:
		/*
		$options = vB::getDatastore()->getValue('options');
		$params['buttons']['facebook'] = (bool)$options['facebookactive'];
		 */
		$params['buttons']['sampleproduct'] = true;
	}

	/*
		Called when checking if Third party connection blocks should be displayed on the registration form.
		Use this hook if your product cannot extend the vB_Api_ExternalLogin::showExternalRegistrationBlock()
		function
	*/
	public static function hookShowExternalRegistrationBlock($params)
	{
		// array of {string productid} => {bool show button}.
		$params['blocks'];
		// By default, populated with facebook button:
		/*
		$options = vB::getDatastore()->getValue('options');
		$params['blocks']['facebook'] = (bool)$options['facebookactive'];
		 */
		$params['blocks']['sampleproduct'] = true;
	}

	/*
		Called right after a user is deleted, but before the `userauth` records are removed.
		Use this hook if your product cannot extend the vB_Library_ExternalLogin::postUserDelete()
		function.
		The extension or this hook should take care of any additional cleanup required by the product
		if it stores any user data outside of `userauth`.
	*/
	public static function hookExternalLoginPostUserDelete($params)
	{
		// integer userid of deleted user.
		$params['userid'];
		// Note that at this point, userauth records are still available iff the deleted user previously
		// linked their accounts.
		$authRecord = vB_Library::instance('YourPackage:ExternalLogin')->getUserAuthRecord(null, null, $params['userid']);

		if (!empty($authRecord))
		{
			vB_Library::instance('YourPackage:ExternalLogin')->doFullCleanup($authRecord);
		}
	}

	/*
		Called when generating the list of template groups.  Allows altering the list or adding to it.
	*/
	public static function hookTemplateGroupPhrase($params)
	{
		//This is a map of template group name to phrase name.  The former is used as the prefix to
		//determine if a template is part of the group, the latter is the phrase used to display the
		//group name
		$params['groups']; //Editable

	}
}
