Hook - Action

[The Wizard]

Hello:

I would like someone to check this out before I go and use it -

I place add_action_hook.php in my main SMF dir where SSI.php is -

add_action_hook.php

Code Select Expand


<?php

// If SSI.php is in the same place as this file, and SMF isn't defined this is being run standalone.
if (file_exists(dirname(_FILE_) . '/SSI.php') && !defined('SMF'))
        require_once(dirname(_FILE_) . '/SSI.php');

// Hmm... no SSI.php and no SMF?
elseif (!defined('SMF'))
       die('<b>Error:</b> Cannot install - please verify you put this in the same place as SMF\'s index.php');

// integrate_pre_include - defines the file that contains the your_action_add_hook function
add_integration_function('integrate_pre_include', '$sourcedir/Subs-Wizards_Item_Gallery.php');

// integrate_actions - defines the function to be used to add the new action every time SMF is loaded.
add_integration_function('integrate_actions', 'wizard_add_hook');

?>


I place Subs-Wizards_Item_Gallery.php in the Sources file

Subs-Wizards_Item_Gallery.php

Code Select Expand


<?php

// place this file in the Sources file

if (!defined('SMF'))
        die('Hacking attempt...');

function wizard_add_hook(&actionArray) {
         $actionArray['wizard'] = array('removeItem.php', 'template_wizard');
}  

?>


I place removeItem.php in the Sources file

removeItem.php

Code Select Expand


<?php
// place this file in the Sources file

if (!defined('SMF'))
        die('Hacking attempt...');

function template_wizard () {

echo '<B>Hello Bill this is a test of the Hook System</b>';

} // End of Function template_wizard bracket
?>


Then I point my browser to http://www.myforum/forum/add_action_hook.php

If all goes well I see a blank page then I can remove add_action_hook.php.

Then if I point my browser to http://www.myforum/forum/index.php?action=wizard
I should get the default template and a message saying - "Hello Bill this is a test of the Hook System" in bold.

Please let me know if I did any coding wrong.

I do have a question or two -

1. Do I have to have removeItem.php in the sources dir or can I put it in a dir called Wizard?
2. If I can have removeItem.php in the Wizard dir what do I have to add to Subs-Wizards_Item_Gallery.php to direct it to removeItem.php?

[emanuele]

The general idea is correct.
There is just one issue and one suggestion.

Let's start with the suggestion: you can have everything in one file:

Code Select Expand

<?php

// place this file in the Sources file

if (!defined('SMF'))
        die('Hacking attempt...');

function wizard_add_hook(&actionArray) {
         $actionArray['wizard'] = array('Subs-Wizards_Item_Gallery.php', 'template_wizard');
}  


function template_wizard ()
{

echo '<B>Hello Bill this is a test of the Hook System</b>';

} // End of Function template_wizard bracket
?>


Next post (so I can keep it better separated) the issue.

[emanuele]

Here it is the issue (well, it's more good practice): one important thing that SMF does is to keep the "computation" separated from the "presentation".

What does that mean?
The easiest way to look at it is:
1) if you have to do for example a query you keep the related code in a file that goes into the Sources directory;
2) if you have to output some html you put the code into a file in the Themes directory;
3) and you never call a function in a file in the Sources directory from a file in the Themes directory and vice versa (okay, that's not always true, it's an exaggeration to make it simple).

So your next question will be: and how the heck will I output something?
Good one.
To make Sources and Themes dialogue you have a simple way: $context. You can store in this variable the result of your "computations" (i.e. queries, etc.) and display them into the template.

So, what is the proper form for that code?
You need two files:
1) Subs-Wizards_Item_Gallery.php => to be placed in the Sources directory
2) wizard_item_gallery.template.php => to be placed in the Themes/default directory

In Subs-Wizards_Item_Gallery.php you will have:

Code Select Expand

<?php

// place this file in the Sources file

if (!defined('SMF'))
        die('Hacking attempt...');

function wizard_add_hook(&actionArray) {
         $actionArray['wizard'] = array('Subs-Wizards_Item_Gallery.php', 'wizard');
}  


function wizard ()
{
   global $context;

   loadTemplate('wizard_item_gallery'); // this command loads the template file (wizard_item_gallery.template.php)
   $context['name'] = 'Bill'; //This is just an example to give you an idea of how it works the communication between source files and theme system

} // End of Function wizard bracket
?>


Then the wizard_item_gallery.template.php:

Code Select Expand

<?php

function template_main () // The name of this function can be defined elsewhere, but to keep it simple for now, let's say that it is always template_main
{
 global $context;

 echo '<B>Hello ' . $context['name'] . ' this is a test of the Hook System</b>';
}


I know it seems complex ("heck I could use just one file and two functions, instead I have to use three functions and two files, that's plain crazy!") , but in the end it's no so difficult and it helps a lot in keeping things organized and it's much easier to change and read in the long term (well...more or less ).

I'm pretty sure you will hate me sooner or later...unless you already hate me now!
Well, I hope to be able to help you understand SMF.

ETA: fixed the wrong name.

[The Wizard]

Hate you? No I don't. I understand you are really trying to help me understand how it works and for that I'm greatfull.

as for keeping stuff organized I understand that and have been moving in this direction already so this is no big suprise. I do wish I could just have one file call wizard where I could put everything including the images, but it seems smf is shall we say set up weird? 

So I'm going to look over your code and then try it out.

Wiz

[emanuele]

You can organize everything in directories, yes. I didn't enter into these details to start with simple things and avoid yet another layer of complexity.

Next time.

[The Wizard]

Hello:

I followed the instructions and uploaded the three files and the hook itself took. I used the action wizard and was taken to the default template, but it had this error on it -

Unable to load the 'wizard_item_gallery' template.

any idea where I went wrong?

[The Wizard]

[emanuele]

Dumb me...
It's wizard_item_gallery.template.php, not template.blablabla.php...sorry...

[The Wizard]

Ok so in

Subs-Wizards_Item_Gallery.php

change the code to this -

Code Select Expand

loadTemplate('wizard_item_gallery.template.php');

Do I also need to rename

template.wizard_item_gallery.php

to

wizard_item_gallery.template.php

?

[emanuele]

No, the code is fine.
The only wrong thing was the name of the file.
You only need to rename the file and leave the code as it is.

[The Wizard]

Yea it worked! Now whats the next lesson? 

[emanuele]

* emanuele doesn't remember any more what was the next topic... lol

One thing was how to use sub templates.
The other was how to organize the code in directories.

Let's start with the easy one: directories.
Let's say that SMF has three "domains": Source, Themes, languages.
These should be kept separated as much as possible (i.e. no html in source, not "computation" in themes and only language strings in languages.
That said, if you want, you can keep your code organized in a single directory within each of these domains. In other words you can create a directory in each of these 3 directories and put your code inside it.
That approach is usually used my "big" mods that has a number of files and want to make easier for the users (and for the developers) to find those files, of course if you have just one source file, one template and maybe one language it's not so useful to create a subdirectory to keep one file.
If you want to follow that route you should simply always add the directory in front of any place you are loading these files.
For example:

Code Select Expand

loadTemplate('wizard_dir/wizard_item_gallery')
rather easy.

So recap: source, themes and languages should always be kept separated.
Within that separation you can keep your files in a subdirectory.
Example of a "proper" separation:

Code Select Expand


/smf/
   |- Sources/
           |- wizard/ <= your source files under here
   |- Themes/
           |- default/
                    |- wizard/ <= your theme files under here
                    |- languages/
                            |- wizard/ <= your language files under here


[The Wizard]

Thanks for clearing that up for me.

I have two questions -

1.- Should images for my mod go into one of the default theme files or should they go into my sub directory?

2. How do I get add_action_hook.php to run in the package manager? I just can't have the users type in the url and the add_action_hook.php file so how to you make it auto run so to speak?

[emanuele]

1.- Should images for my mod go into one of the default theme files or should they go into my sub directory?

Basically it's up to you.

2. How do I get add_action_hook.php to run in the package manager? I just can't have the users type in the url and the add_action_hook.php file so how to you make it auto run so to speak?

<code> tag if you have only to add hooks
<database> tag if you need to modify the database (i.e. add columns or tables)
You use the two like for example the <modification> tag:

Code Select Expand

<install for="2.0 - 2.0.99">
<code>install.php</code>
</install>
<uninstall for="2.0 - 2.0.99">
<code>install.php</code>
</uninstall>