Register Members List Search Today's Posts Mark Forums Read

Reply
 
Article Options
[How to] Write Plug-ins/Hooks
Brad
Join Date: Nov 2001
Posts: 4,766

Dixie
by Brad Brad is offline 07 Jun 2005
Rating: (2 votes - 4.50 average)

This is your basic guide to making plug-ins and hooks, as we are all coming over from the 'hack the files' mentality I am posting this thread more for people that are used to hacking the 3.0.x source code and looking to port modifications. Although a newbie should be able to come away with a good understanding of how to do this to .

Things to consider

Ok before we get started here are a few things to keep in mind. First and foremost plug-ins are stored in the database, serlized, unserlized and evaled on page generation. If you code preforms badly with such a wrapper forget making a plug-in and just hack it, trust me you'll thank yourself for it when your forum gets large.

Second thing, hooks will not get you into every corner of the code. Some things will always be done best with a hack. For example if you are looking to add something but need to query the db for some extra data and want to avoid and extra query (in other words you are going to modify an existing one with a join or such) forget it and hack it in, there are no hooks that let you modify existing queries.

Last but not least hooks are not magic, don't add a million of them and expect your forum to run as fast as it did when you first installed it. Only plug-in/hack-in what you really need!

Ok enough with the boring stuff, lets add our first plug-in!

Basics:

First thing you need to do is make sure plug-ins are enabled, you can find this option in the admin cp by browsing to vBoptions -> Select Plugin/Hook System from menu -> Set Enable Plugin/Hook System to yes.

Now head to the add plug-in page located at http://www.yoururl.com/forum/admincp/plugin.php?do=add

Lets go over what all these options mean:

Hook Location: This is where the php code will be executed at, hook locations at defined all across vBulletin. You can find them by opening and php file and searching for the var $hook. When you find a bit of php code like this you have found a hook:


Block Disabled:      (Update License Status)  
Suspended or Unlicensed Members Cannot View Code.

See that bit fetch_hook('showthread_postbit_create')? Well the text "showthread_postbit_create" is the name of this hook, if you look in the drop down you will find that listed in there somewhere. Incase you are wondering that hook is located in showthread.php at line 1012

Title: This is the title of your plug-in, use a good name because this is the only thing you have to identify the plug-in in the plug-in manager.

Plugin PHP Code: Can you guess? This is where you put your custom php code, on page generation it is executed at the hook location in the .php files. Note that you do not need <?php ?> tags here, in other words:

wrong:


Block Disabled:      (Update License Status)  
Suspended or Unlicensed Members Cannot View Code.

Right:


Block Disabled:      (Update License Status)  
Suspended or Unlicensed Members Cannot View Code.

Plugin is Active: Allows you to turn the plug-in on/off without removing it. If set to 'yes' php code is ran on page execution.

Edit - Thanks to Revan for this addition:

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):

Block Disabled:      (Update License Status)  
Suspended or Unlicensed Members Cannot View Code.

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.
Tips

At first approach coding the plug-in like a hack.

Open the php file you would normally edit and get your mind around the new code.

Once you have a good understanding of the new code you should start looking for where you need to add your custom php. Once you find the right location in the code start looking for a nearby hook, if you don't see one you can work with you are out of luck!

Edit- Thanks to KirbyDE for his addition:

Something that might come in handy for those developing Plugins:

In class_hook.php FIND

Block Disabled:      (Update License Status)  
Suspended or Unlicensed Members Cannot View Code.

BELOW that ADD

Block Disabled:      (Update License Status)  
Suspended or Unlicensed Members Cannot View Code.

Then (if debug mode is turned on) you can see which hooks are being called, and when they are being called.
Once you find your hook note its name and apply your changes in the admincp, from here on out you are on your own

Last edited by Brad.loo; 14 Jun 2005 at 05:42..
Views: 54041
Reply With Quote
Comments
  #2  
Old 09 Jun 2005, 18:01
amykhar's Avatar
amykhar amykhar is offline
 
Join Date: Oct 2001
Real name: Amy
Thanks, Brad. It's nice to have a plugins for dummies tutorial to get started with
__________________
amykhar.com
----------------------------------------
I do not respond to PM requests for coding assistance.
Reply With Quote
  #3  
Old 09 Jun 2005, 18:49
Logikos Logikos is offline
 
Join Date: Jan 2003
Excellent! Now i understand the hooks system.
__________________
Full Time PHP Developer
Please feel free to contact me if you have any paid work to be done.
Reply With Quote
  #4  
Old 09 Jun 2005, 18:55
amykhar's Avatar
amykhar amykhar is offline
 
Join Date: Oct 2001
Real name: Amy
I'm glad somebody does

The first hack I looked at porting doesn't look like it will be able to use the hook system, unfortunately. I really wish jelsoft had come up with a more extensible way to format queries. If the queries have to be changed, we run into the same problems we had before.

I would love it if the arguments to a query were set up in an array format that could be easily added to. That way, if we are forced to add into an existing query, the user could modify the arguments to the query rather than the query itself. It would be so much easier to prevent hack conflicts and installation errors that way.

Amy
__________________
amykhar.com
----------------------------------------
I do not respond to PM requests for coding assistance.
Reply With Quote
  #5  
Old 09 Jun 2005, 18:58
Brad's Avatar
Brad Brad is offline
 
Join Date: Nov 2001
Amy: If you see a good spot for a hook request it at vBulletin.com, this is one of the main reasons we are encourged to hack the beta
__________________
Former vB.org <something>
Reply With Quote
  #6  
Old 09 Jun 2005, 19:02
Logikos Logikos is offline
 
Join Date: Jan 2003
Brad i have a question, I ported my icons hack. But i have to hack the admincp/forum.php for the option to show up in the admincp. Does the Hooks system work in the admincp/ dir? From what i read in the code it doesn't.

Maybe you have another solution to this.

Its just this:

Block Disabled:      (Update License Status)  
Suspended or Unlicensed Members Cannot View Code.

__________________
Full Time PHP Developer
Please feel free to contact me if you have any paid work to be done.
Reply With Quote
  #7  
Old 09 Jun 2005, 19:03
Andreas's Avatar
Andreas Andreas is offline
 
Join Date: Jan 2004
Real name: Andreas
Unfortunately there are currently no hooks within the AdminCP.
Therefor you will have to modify the files.
Reply With Quote
  #8  
Old 09 Jun 2005, 19:07
Logikos Logikos is offline
 
Join Date: Jan 2003
Originally Posted by KirbyDE
Unfortunately there are currently no hooks within the AdminCP.
Therefor you will have to modify the files.
Then whats the point! Bah, so much for that...
__________________
Full Time PHP Developer
Please feel free to contact me if you have any paid work to be done.
Reply With Quote
  #9  
Old 09 Jun 2005, 19:09
Brad's Avatar
Brad Brad is offline
 
Join Date: Nov 2001
Originally Posted by Live Wire
Then whats the point! Bah, so much for that...
Less file modification = easier to upgrade.

Like I said, you see a useful place for a hook request one at vBulletin.com!
__________________
Former vB.org <something>
Reply With Quote
  #10  
Old 09 Jun 2005, 19:09
amykhar's Avatar
amykhar amykhar is offline
 
Join Date: Oct 2001
Real name: Amy
I am not sure a hook would help my problem. For example, if you look at index.php, you see a query to get the logged in users.


Block Disabled:      (Update License Status)  
Suspended or Unlicensed Members Cannot View Code.

Now, I need to know the useragent field from the sessions table. So, I have to change the query to:


Block Disabled:      (Update License Status)  
Suspended or Unlicensed Members Cannot View Code.

I don't think a hook would change that for me. But, if each query had it's arguments defined in a structure that defined the columns to read, update, or insert and had a way to set up joins, etc. outside the query in a clean, easy to modify way (such as adding arguments to an array), then we could hack right in there without worry of conflicts or sql syntax issues.

Amy
__________________
amykhar.com
----------------------------------------
I do not respond to PM requests for coding assistance.
Reply With Quote
  #11  
Old 09 Jun 2005, 19:15
Andreas's Avatar
Andreas Andreas is offline
 
Join Date: Jan 2004
Real name: Andreas
Hmm .... a Query class!
That's what would be needed.

Example

Block Disabled:      (Update License Status)  
Suspended or Unlicensed Members Cannot View Code.

Reply With Quote
  #12  
Old 09 Jun 2005, 19:26
amykhar's Avatar
amykhar amykhar is offline
 
Join Date: Oct 2001
Real name: Amy
Originally Posted by KirbyDE
Hmm .... a Query class!
That's what would be needed.

Example

Block Disabled:      (Update License Status)  
Suspended or Unlicensed Members Cannot View Code.
Exactly!
__________________
amykhar.com
----------------------------------------
I do not respond to PM requests for coding assistance.
Reply With Quote
  #13  
Old 09 Jun 2005, 20:26
Fusion Fusion is offline
 
Join Date: Oct 2001
Originally Posted by KirbyDE
Hmm .... a Query class!
That's what would be needed.

Example

Block Disabled:      (Update License Status)  
Suspended or Unlicensed Members Cannot View Code.
Actually, that's an excellent idea.
Reply With Quote
  #14  
Old 09 Jun 2005, 22:12
Revan's Avatar
Revan Revan is offline
 
Join Date: Jan 2004
Real name: Fillip
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):

Block Disabled:      (Update License Status)  
Suspended or Unlicensed Members Cannot View Code.

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):

Block Disabled:      (Update License Status)  
Suspended or Unlicensed Members Cannot View Code.

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

Last edited by Marco van Herwaarden; 10 Jun 2005 at 16:47.
Reply With Quote
  #15  
Old 10 Jun 2005, 07:28
Cap'n Steve's Avatar
Cap'n Steve Cap'n Steve is offline
 
Join Date: Feb 2004
Originally Posted by Brad.loo
First and foremost plug-ins are stored in the database, serlized, unserlized and evaled on page generation. If you code preforms badly with such a wrapper forget making a plug-in and just hack it, trust me you'll thank yourself for it when your forum gets large.
Could you elaborate on this? Are there some known problems with eval() or something else?
Reply With Quote
Reply



Currently Active Users Viewing This Thread: 1 (0 members and 1 guests)
 
Article Options

Posting Rules
You may not post new threads
You may not post replies
You may not post attachments
You may not edit your posts

BB code is On
Smilies are On
[IMG] code is On
HTML code is Off


New To Site? Need Help?

All times are GMT. The time now is 19:39.

Layout Options | Width: Wide Color: