Hooks

[NanoSector]

Just asking for some input here. For those of you finding hooks difficult, what exactly is the difficult part in it? Is it the system used, the documentation we provide or something else?

Any comment is welcome, but please stay on topic

[JBlaze]

This should probably go in SMF Coding Discussion

[NanoSector]

Wasn't entirely sure where to put it, figured I'd reach a larger audience in chit chat. Moved   

[margarett]

From someone who just recently got a semi-grip on hooks

Issues:
* To know which ones exist. Why? Because I took too long to find this: http://wiki.simplemachines.org/smf/Integration_hooks
* To know *when* to call which hook. The previous link helps also, although in this case you clearly need to know what you're looking for.
* To know how to actually call them and how to write proper functions. In this case, having a look at existing MODs is the best possible action

Advantages:
* Obviously, no (or less) file edits which pretty much assures no compatibility issues with other MODs
And, to me, *THE* advantage:
* Huuuuuuge time saving when writing MODs.

Comparison between regular and hook-aholic MOD creation/editing:
a) normal: I have a 200-lines install.xml file that touches some files. Eg: index.php for a new action, Subs.php for a menu item, ManageSettings.php for admin options and Modifications.english.php for 50 new text strings. Development:
1 - I edit code directly in SMF codebase until it matches my intentions
2 - I do a file contents compare and create a lengthy and boring-to-do install.xml with every MOD operation
3 - I finish my package and test it in a clean SMF install. It install, it works. Wohohooooo!
4 - Because I'm careful, I do a file contents compare to check if the replace/add before/add after operations didn't accidentally messed indentation or line breaks. It's broken, damn!!!
4.1 - I uninstall the MOD, fix install.xml, repack the MOD, reinstall and repeat 4 until it's fine
5 - I submit my MOD to modsite.
6 - Someone notices a bug or requests a new feature. So you repeat from 1 to 5. Don't forget 4 and 4.1

b) hooks: I have a 20-lines package-info.xml, an install.php/uninstall.php, a MyCustomMod.php and a MyCustomMod.english.php file
0 - I create a MyCustomMod.php with the basic functions declaration (necessary for hooks) so that I don't have errors. Then I create all files necessary for the mod package itself: package-info.xml, install.php, remove.php and an empty MyCustomMod.english.php
1 - I install the MOD in my clean SMF. Of course it does nothing
2 - I develop code directly in my custom files --> MyCustomMod.php and MyCustomMod.english.php until it fits me
3 - I put these 2 files in my mod package. Txaram! Done
4 - I submit my MOD to modsite
5 - Someone notices a bug or requests a new feature. So you repeat from 2 to 4. Done.

Of course, not *EVERYTHING* can be accomplished with MODs... I have some MODs and only 1 of them is completely hook-aholic. I'm working on a MOD for 2.1 that started as a "regular" .xml install that consumed me fixing the damn file. Now it's fully hook-aholic and I save an *insane* amount of time by working directly on my custom files.

[vbgamer45]

The one thing I wish for a way to know which hooks are installed/running a way to disable hooks if there is a way already. I kind of like seeing the file changes since then you know where the mod is adding code to know.

For hooks themselves I think simple guides on how to do certain actions with hooks vs file edits and do a comparison.

[Kindred]

Emanuele wrote a mod which lists the installed/used hooks...  I don't know of any which disable individual hooks, but the repair_settings tool can remove all hooks

[br360]

Good explanation margarett, thank you.

So in regards to an upgrade or installing a fresh set of files- I thought I read on here somewhere that any hooks would most likely remain installed. (while the mods that edit files would most likely not if it's a clean install)

If one was to do an upgrade or fresh file install, what issues would they have if the hooks were still there- and would they be able to just delete the hook files once the upgrade/fresh install was complete?

[margarett]

Good explanation margarett, thank you.

So in regards to an upgrade or installing a fresh set of files- I thought I read on here somewhere that any hooks would most likely remain installed. (while the mods that edit files would most likely not if it's a clean install)

If one was to do an upgrade or fresh file install, what issues would they have if the hooks were still there- and would they be able to just delete the hook files once the upgrade/fresh install was complete?

Hooks are stored in smf_settings table (thus present everywhere in $modSettings). If you remove the files that a hook is supposed to use, 2.0 will silently disregard it. 2.1 presents you an error in error log but still breaks nothing But 2.1 has a maintenance page for hooks management so you can just go there and remove the culprit in that case

[Suki]

* To know which ones exist. Why? Because I took too long to find this

2.1 adds a huge amount of new hooks, its on my todo list to hunt them all and at least give a practical explanation on what they do since I'm not really a huge fan of editing the wiki.

Emanuele wrote a mod which lists the installed/used hooks...  I don't know of any which disable individual hooks, but the repair_settings tool can remove all hooks

Its included on 2.1 by default.

[live627]

I don't mind editing the wiki.

[Bigguy]

Not only which ones exist but also a small tut on what code goes with them to make them work in the ways they can work in would be great.

[Arantor]

The problem is that you can do many things with hooks that are not necessarily intended by the hook itself meaning that it is rather difficult to give you concrete examples.

Let me give you a few examples of what I mean from my current mod project, Levertine Gallery, which is *entirely* hook driven.

First up, only two actual hooks get touched during installation - integrate_pre_include to load the LevGal-Bootstrap.php file and integrate_pre_load to actually initialise it.

It's called sufficiently early because it does its own pretty URLs stuff and needs to rewrite the URL internally before cleanRequest() gets called, hence integrate_pre_load has to be used.

It then proceeds to attach things to:
integrate_redirect - to fix cases of redirection to empty URL and to prevent PHPSESSID being inserted inside redirect links
integrate_menu_buttons - to add its menu item
integrate_load_theme - to begin a new output buffer that starts before ob_sessrewrite (and thus will be called after it) to fix cases of PHPSESSID and ?debug links from breaking the gallery URLs; this *also* doubles up as something to inject tags into <head> because $context['html_headers'] cannot be relied upon due to bad mod authors, and it handles cases whereby any of the media bbcode gets used because it collates every use of the bbcode and only does a single query at the end to get all the items rather than one query every single item on a page (e.g. consider a post that links half a dozen media items)
integrate_bbc_codes - to declare the bbcodes used by the gallery
integrate_actions - to declare the media action, and to load language files and other stuff before entering things like the who's online or profile areas, and it also handles binding hooks for the admin and profile areas respectively (rather than cluttering the settings table, it only declares what it *needs* and binds them softly when they will be needed)

The hooks are scary powerful if you can think of what will be available at the time the hook gets loaded; for example I'm absolutely sure that integrate_load_theme was never 'intended' to be used to create a new output buffer at that point in time, it just happened to be the only hook that ran late enough to be useful and early enough to do what it has to do.

There's simply no way to write a tutorial on 'what you can do with a hook' because you can do *anything* in hooks if you are prepared to get your hands dirty with the running state of everything. Even down to rewriting the HTML that goes out to the user if you really want to, that's completely doable.

To write such a tutorial would amount to 'here's a tutorial on writing a mod but the only thing the tutorial shows you is how to write *this exact mod*', like most of the 'how to' tutorials out there.

You can even get very creative; for example I wanted to add a scheduled task - but I didn't want to modify the scheduled tasks file, and I wanted it in its own class... so I just did a piece of eval magic to declare the function I needed which simply acts as a wrapper around my class, because scheduled tasks requires the function to be named just so.

Code Select Expand

public static function defineScheduled()
{
// This is truly unpleasant but it's the only way to make it work without randomly just declaring a function in a class definition.
eval('function scheduled_levgal() { return LevGal_Helper_Scheduled::execute(); }');
}

It is also so much easier to list all the hooks now since call_integration_function is a thing, where it wasn't when I originally made a list of all the hooks (which is what eventually became the wiki... in fact I think the wiki still uses the notation I wrote at the time when SMF could only call one function per hook, as it was written pre-RC4)

[Bigguy]

The problem is that you can do many things with hooks that are not necessarily intended by the hook itself meaning that it is rather difficult to give you concrete examples.

Ok from reading your post I understand most of what you say, but can a tut not be posted just about the most basic functions according to what that particular hook is supposed to do. ?? Btw, that sounds like a real nice project your workin on.

[Arantor]

That's just it, of course it can't.

Let me give you probably the simplest example: integrate_actions. This is the one that controls the actions list (the map of index.php?action=... to a file and function)

At its simplest, you can just add a new action. Literally just a case of $actionArray['mynewaction'] = array('MyFile.php', 'myfunction'); or whichever way around it is.

But you can do more than that - you can rewrite existing actions to point to new files. You could even remove actions if you wanted. Or indeed mess with literally anything else in SMF at that point in time; you could redeclare anything in $context, or $modSettings, or $settings... it's just a point in execution from start to finish whereby you can interact with everything in global and the specific stuff it's giving you to play with on top.

I suppose the canonical example there is a good enough one, but only because the hook is so focused on what it offers and when. Most hooks are not so generously inclined and most run at times that would be useful for so many things.

And yes, my gallery project is certainly turning out better than expected But doing its own pretty URLs and absolutely no file edits adds a certain level of challenge to the mix.

[Bigguy]

Ok, you say above that this can do this:

ntegrate_menu_buttons - to add its menu item

Now from what you say, I take it this can do a lot more than that. If it's main function is to integrate menu buttons, then why not write a short tut on how to do that. Once people have the basics I'm sure they can take it from there. Or am I way off base. ??

Whenever ya get that mod going I would love to try it out.

* Bigguy leaves to let the dog in

[Arantor]

Yes, of course it can.

At every hook, you have implicit access to everything currently in SMF's running state. $context, $modSettings, $settings, etc. and you can do anything with all of those if you want.

The name then primarily dictates what will have be done by the time you call it, what will be available in those things and maybe some extra information.

Its main function is to do that but there's all kinds of strange edge cases there too... new button goes where? Adding sub menus? Changing access on existing menus? (Especially the admin menu)

That's really the problem: anyone smart enough to be able to write a mod that actually uses this stuff almost doesn't *need* a tutorial and anyone that does get a tutorial just ends up only having access to what the tutorial does anyway.

Like I said, a tutorial for writing a mod only gets you that mod. It doesn't teach you how to make mods, only how to make that one specific mod.

[Bigguy]

That's really the problem: anyone smart enough to be able to write a mod that actually uses this stuff almost doesn't *need* a tutorial and anyone that does get a tutorial just ends up only having access to what the tutorial does anyway.

I'm sure that there will be a lot of people out there that will be able to learn off of a basic tutorial and run with it. I think all they need is a starting point. After all this is a forum and we are all here to learn and discuss this crazy thing we call SMF, lol.

[Arantor]

That's simply not been my experience of working with people learning to program.

I'm reminded of an experience recounted in "The Redemption of Althalus" where the titular character can't read and is shown a book, with the word for cow in it. The conversation ends up going something like this:

"I've only been doing this for five minutes and already I can read."
"Yes, as long as all you want to read about is cows."

I'm sorry, I simply do not agree with your premise that a tutorial for this stuff would actually be of use.

[Bigguy]

I respect your opinion, I really do. I think leaving people in the dark about it though is a lot worse. (just my opinion)

[Hj Ahmad Rasyid Hj Ismail]

+1 @margarett for reply #3.

I started after an advice given by emanuale "elsewhere" and after helping samborabora. And as stated by margarett, I also create or convert my mod to hook by reading mod(s) as well as the wiki, again and again and again.

I still read mods and smf code. It seems funny but that's how I learned to code. If somebody like me, with limited knowledge and experience, can do it, I am sure that anybody with a little bit of help can.

I guess I can share how my hook mods are written in their support page. I will post an update to this later.

Edited: Here is one tutorial for CPTTA hook mod: http://www.simplemachines.org/community/index.php?topic=527314.msg3752859#msg3752859. If I am not that busy, I will slowly write tutorial for other hook mod(s) as well.