TYPO3 Hooks Tutorial (using the extension wfqbe)

So here’s a little tutorial on how to use hooks in TYPO3, I hope this is helpful, feel free to ask any questions. A little disclaimer: I have no “formal” education in this and I’m mostly a self-taught developer, so should I occasionally use the wrong terminology feel free to tell me :).

Helpful knowledge: You should know the basics of extension building (creating a new extension with the kickstarter should suffice), if you haven’t worked with wfqbe so far you should get to know the extension first. wfqbe requires some basic SQL skills.

I’m using a hook to extend the extension wfqbe. wfqbe is a great and powerful tool to access MySQL databases via the TYPO3 Frontend and display and edit the content of database entries. As default wfqbe accesses the TYPO3 database, but you can also access pretty much any MySQL [edit: Mauro pointed out, that wfqbe will work with any database supported by ADOdb] database. It even comes with built-in AJAX capabilities (xajax) but I haven’t used that yet. If you haven’t started working with wfqbe you might want to work through the documentation of it. It’s fairly well documented. You will find yourself using the tool for all kinds of different purposes and it will spare you lots of work of having to write a new extension for everything as it is highly configurable through the use of TypoScript and: hooks.

This will come in handy as soon as you start building more complex applications and you “outgrow” the standard functions of wfqbe. Our example will actually be a rather trivial one. We want to use wfqbe to edit fe_users entries and assign multiple user groups to the entry. So far this is no problem for wfqbe (the edit/insert tool is actually pretty straight forward) but there is one thing wfqbe cannot do: assign multiple user groups to a fe_users entry when you have more than one select form field that writes into fe_user.usergroups.

We had to build an employees database where the database had to differentiate not only at which branch of the company the employee is located but also what his position is (example: {Smith: staff manager, research center}). Thus, I added two fields to the edit/insert form both of which should write into fe_users.usergroups. Unfortunately the second entry always cancelled the first entry, so only the second one was written. This is where hooks come into the play.

What exactly is a hook? Let’s take a look in the source code for that (the wfqbe documentation will tell you where the hooks are at in the wfqbe sources). Somewhere around line 1200 in the file EXT:wfqbe/pi1/class.tx_wfqbe_insert.php you will find this code:

// Hook that can be used to pre-process a parameter (from an insert form) before inserting the new row
if (is_array($GLOBALS['TYPO3_CONF_VARS']['EXTCONF']['wfqbe']['processProcessInsertValues'])) {
foreach($GLOBALS['TYPO3_CONF_VARS']['EXTCONF']['wfqbe']['processProcessInsertValues'] as $_classRef) {
$_procObj = &t3lib_div::getUserObj($_classRef);
$insert_data = $_procObj->process_insert_values($insert_data, $data, $blocks, $this);
}
}

Congratulations, you found your first hook :). Let’s look at what the hook does:

  1. It checks whether the global variable array $GLOBALS[‘TYPO3_CONF_VARS’][‘EXTCONF’][‘wfqbe’][‘processProcessInsertValues’] is set.
  2. If the array is set, all the values in it will be processed.
  3. The array values are references to the class that will take care of processing the data (as you will soon see).
  4. the variable $insert_data will be changed to the return value of the function process_insert_values() in the class referenced in the array.

Ok, all we need to do to alter the data in insert data is to register a class (somewhere), put the function process_insert_values() in it and let the whole thing go wild? Understood? No? Then let’s take the whole thing slowly.

  1. Fire up your kickstarter and create a new extension. You might want to name it user_wfqbe_hooks or something like that, so you can put all the future classes that access wfqbe hooks into that extension (that’s going to save you lots of performance once you start using hooks more regularly, no need to create a new extension for every little task there is). Set its status to experimental so nobody will ever be tempted to use that thing without asking you about it first.
  2. Create an (empty) Frontend Plugin for your extension, so that the kickstarter will create all the necessary files you need for your extension to work (you need the ext_localconf.php)
  3. Save and install the extension.

Now we’re set to go to. Open the ext_localconf.php and add the following line

$GLOBALS['TYPO3_CONF_VARS']['EXTCONF']['wfqbe']['processProcessInsertValues'][] = 'EXT:user_wfqbemultiplefix/res/class.tx_wfqbe_processinsertvalues.php:tx_wfqbe_processinsertvalues';

before the line

t3lib_extMgm::addPItoST43($_EXTKEY, 'pi1/class.user_wfqbemultiplefix_pi1.php', '_pi1', 'list_type', 1);

This registers the class that accesses the hook in TYPO3. But for this to work we need the actual class. So let’s create the file EXT:user_wfqbemultiplefix/res /class.tx_wfqbe_processinsertvalues.php and define the class we need by writing the following code into the empty file:

<?php

class tx_wfqbe_processinsertvalues {
function tx_wfqbe_processinsertvalues () {}
}
?>

We now have the empty class and its empty constructor set up, but we need one more thing. The hook references the function process_insert_values() so we need to add the function and let it do the work we want it to do:

<?php

class tx_wfqbe_processinsertvalues {
function tx_wfqbe_processinsertvalues () {}

function process_insert_values ($insert_data, $data, $blocks, $callingObj) {

/* This is where the code goes */

}
}
?>

You can use the function t3lib_div::debug($variablename) to output the content of the variables that have been passed to the function. You should always do this before starting to wildly guess which variable does what (this is good practice for any extension building btw). In our example $insert_data contains the data wfqbe will use to build the create or update query, $data contains the original POST-variables, $blocks contains the information that was used to build the insert/edit form. $callingObj references the object that called the function (d’uh). So our function has to find the relevant data in the $data array and write it into the $insert_data and finally return the $insert_data variable so that wfqbe will be supplied with data that makes sense. So here’s the final code (this last bit has nothing to do with hooks per se, so I won’t go into detail):

<?php

class tx_wfqbe_processinsertvalues {
function tx_wfqbe_processinsertvalues () {}

function process_insert_values ($insert_data, $data, $blocks, $callingObj) {

$grouplist = array();

// Debug Outputs, activate for development purposes only
// t3lib_div::debug($insert_data);
// t3lib_div::debug($data);
// t3lib_div::debug($blocks);
// t3lib_div::debug($callingObj);

// This ONLY changes anything, if wfqbe is set to alter the table fe_user
if ($blocks[“table”] == “fe_users”) {

// find out which form elements edit fe_user.usergroup
foreach ($blocks[“fields”] as $key => $field) {
if ($field[“field”] == “usergroup”) {
//add the group id to the grouplist
foreach ($data[“$key”] as $group) {
$grouplist[] = $group;
}
}
}

// construct a comma separated string with the groups ids, delimited by ‘quotes’ (the mysql-query needs them)
$insert_data[“usergroup”] = “‘”;

foreach ($grouplist as $key => $group) {
if ($key == 0) {
$insert_data[“usergroup”] .= “$group”;
} else {
$insert_data[“usergroup”] .= “,$group”;
}
}
$insert_data[“usergroup”] .= “‘”;

}

// return $insert_data with the new list of usergroups
return $insert_data;

}
}

?>

Advertisements

2 Responses to TYPO3 Hooks Tutorial (using the extension wfqbe)

  1. Hi!
    Nice tutorial, just a little specification: wfqbe allows you to connect to any dbms supoprted by adodb, not mysql only.

    Enjoy using wfqbe 🙂

  2. […] you need to learn more about hooks, then go read it here GD Star Ratingloading…GD Star Ratingloading… Share and […]

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

%d bloggers like this: