[How-to] Hooks and Plugins

[How-to] Hooks and Plugins

by calorie 12 Jun 2005

In hooks_vbulletin.xml you will see things like the following:

Code:

	<hooktype type="general">
		<hook>global_start</hook>
		<hook>global_complete</hook>

The hooktype is just a unigue name for the hook tags within. The hook tags refer specifically to PHP code in the vB files.

The PHP code in the vB files looks like the following:

Code:

	($hook = vBulletinHook::fetch_hook('global_start')) ? eval($hook) : false;

Note how global_start is in a hook tag in hooks_vbulletin.xml and also in the vB PHP code.

To make a plugin hooked to global.php, you create an XML file as follows:

Code:

<?xml version="1.0" encoding="ISO-8859-1"?>
<plugins>
	<plugin active="1" devkey="Name" product="vbulletin">
		<title>Your Title</title>
		<hookname>global_start</hookname>
		<phpcode><![CDATA[//
// START PHP CODE
$foo = "bar";
// END PHP CODE
//]]></phpcode>
	</plugin>
</plugins>

The place in vB PHP code where your global_start plugin runs is where the following occurs in global.php:

Code:

	($hook = vBulletinHook::fetch_hook('global_start')) ? eval($hook) : false;

Basically, you make plugins via XML and your plugins hook to vB PHP code
via <hookname>hook_name</hookname> from the plugins,
which needs to match the fetch_hook('hook_name') in the vB PHP code,
which needs to match <hook>hook_name</hook> in hooks_vbulletin.xml.

You can even make a plugin that hooks to multiple vB PHP files as follows:

Code:

<?xml version="1.0" encoding="ISO-8859-1"?>
<plugins>
	<plugin active="1" devkey="Name1" product="vbulletin">
		<title>Your Title1</title>
		<hookname>global_start</hookname>
		<phpcode><![CDATA[//
// START PHP CODE1
$foo = "bar";
// END PHP CODE1
//]]></phpcode>
	</plugin>
	<plugin active="1" devkey="Name2" product="vbulletin">
		<title>Your Title2</title>
		<hookname>forumhome_start</hookname>
		<phpcode><![CDATA[//
// START PHP CODE2
$bar = "foo";
// END PHP CODE2
//]]></phpcode>
	</plugin>
</plugins>

This latter example runs the first batch of PHP code where the following occurs in global.php:

Code:

($hook = vBulletinHook::fetch_hook('global_start')) ? eval($hook) : false;

And runs the second batch of PHP code where the following occurs in index.php:

Code:

($hook = vBulletinHook::fetch_hook('forumhome_start')) ? eval($hook) : false;

Again, note how <hookname>hook_name</hookname> in the XML plugin
matches fetch_hook('hook_name') in the vB PHP code
matches <hook>hook_name</hook> in hooks_vbulletin.xml.

Further readings...

What is a hook:

-

Spoiler (click to open)

Quote by Snake

Hahaha... that was funny.

^ Is that what you wanted? :nervous:

Don't worry

They're all just having a little fun around here

no harm done

Hooks are basically locations in the vBulletin files, where code can be executed using the plugin system.

So for instance, if a location in the User CP has a hook, you can execute code there - using the plugin system. Of course, actual file modifications can still be executed anywhere you want.

If a location does not have a hook, you will either HAVE to modify the files (something that 3.5 modders try to avoid now, like me) OR you just don't insert the code in the file, and instead ask Jelsoft to add a hook there.

Makes sense?

How to make a plugin:

-

Spoiler (click to open)

I have an addition to this tutorial:

vbulletin_plugins.xml
If you need to tell your users to add a lot of plugins, this will become tedious as much copy/pasting is required. A simpler way would be to use the .xml import. It works just like the importing of templates and phrases, by adding the contained code as a Plugin.
The correct format for a plugin.xml file is like so (thanks to Live Wire):

Code:

<?xml version="1.0" encoding="ISO-8859-1"?>
<plugins>
	<plugin active="1">
		<title>vB Category Icons</title>
		<hookname>forumdata_start</hookname>
		<phpcode><![CDATA[$this->validfields['forumhomeicon'] = array(TYPE_STR, REQ_NO);]]></phpcode>
	</plugin>
</plugins>

Explanations:
<plugin active="1"> - The 'active' attribute determines the default value of 'Plugin is Active' in the Plugin Manager.
<title></title> - Self explanatory, it is the 'Title' field in the Manager.
<hookname></hookname> - The 'Hook Location' you would select.
<phpcode><![CDATA[ ]]></phpcode> - Anything added in the space between these is added to the 'Plugin PHP Code' part.

// end my contribution (if this is being merged into the first post, nothing below this is to be included)

And just for all you lazy people out there, here is an empty set, ready for copypasting into a blank xml file (only the <?xml and <plugins> tags need to be there already):

Code:

	<plugin active="1">
		<title></title>
		<hookname></hookname>
		<phpcode><![CDATA[]]></phpcode>
	</plugin>

I hope this helps hack writers that want to minimise the hassle for the end-user

How to add a new hook location:

-

Spoiler (click to open)

This guide will teach you how to add your own hook locations to your scripts/default vBulletin source code. Note that I assume that you are working within the vBulletin.php files or you have included vBulletin's global.php.

Adding custom hook locations -

Method one:

See paul's thread here for the best method, if you are going to release your modification to the public this is the way you should go:

index.php?t=83390

Method two:

All hooks listed in this drop down live in the .xml file located at /vbroot/includes/xml/hooks_vbulletin.xml

Find this bit of code at the very top of the file:

HTML Code:

<hooks>
	<hooktype type="admindata">
		<hook>admindata_start</hook>
		<hook>admindata_presave</hook>
		<hook>admindata_postsave</hook>
		<hook>admindata_delete</hook>
	</hooktype>

Looks simple eh? Heres what these tags do

<hooks> - anything between this tag and </hooks> will be included in the drop down

<hooktype type="name"> - The name of your hook group, you should group all common hooks under a group so you can find them quickly. Make sure you don't use a name already used by a default hooktype.

<hook> - The name of your hook, this must be the same as the hook's name in the php code

Here is an example of my .xml file, I added three custom hooks under a new hooktype:

HTML Code:

<hooks>
	<hooktype type="loo_custom">
		<hook>loo_custom1</hook>
		<hook>loo_custom2</hook>
		<hook>loo_custom3</hook>
	</hooktype>

The php code:

Adding a hook location to the php code is easy, just make sure you use the correct hook name! Use this bit of php anywhere after your call to global.php to call your custom hook. Also note that you must use the $hook var!

PHP Code:


($hook = vBulletinHook::fetch_hook('hook_name')) ? eval($hook) : false;

Here is an example of my custom hooks working in vBulletin's index.php file:

PHP Code:


// #######################################################################

// ######################## START MAIN SCRIPT ############################

// #######################################################################



($hook = vBulletinHook::fetch_hook('forumhome_start')) ? eval($hook) : false;

($hook = vBulletinHook::fetch_hook('loo_custom1')) ? eval($hook) : false;

($hook = vBulletinHook::fetch_hook('loo_custom2')) ? eval($hook) : false;

($hook = vBulletinHook::fetch_hook('loo_custom3')) ? eval($hook) : false;

As you can see I added them right under a current hook, which mostly defeats the purpose of making custom hooks. But for this post they serve their purpose

Now all you need to do is browse to your admincp's add new plug-in page and test your new hook location! I use this just to make sure it is working correctly:

PHP Code:


echo('Testing hook_name hook');

If that outputs its text above the vBulletin header then you are good to go!.

vBulletin LTS

Spoiler (click to open)

Spoiler (click to open)

Spoiler (click to open)