.. ==================================================
.. FOR YOUR INFORMATION
.. --------------------------------------------------
.. -*- coding: utf-8 -*- with BOM.

.. include:: ../Includes.txt

.. _extending:

Extending the SQL Frontend
==========================

Need your own special handler for, say, the database? Or an own column handler? Or just a simple callback (like in the old SQL Frontend prior to version 3)? That's possible and -- thanks to extbase -- really comfortable as well. Just a few steps to follow:

Step 1: Create an own extension
-------------------------------

The easiest way to create an extension is to create a sub directory within TYPO3's extension directory (typo3conf/ext/) and within that directory you at least need to create the following three things:

- **ext_emconf.php** with all necessary information (see http://docs.typo3.org/typo3cms/CoreApiReference/ExtensionArchitecture/DeclarationFile/Index.html?highlight=ext_emconf)
- **Classes/ subdirectory** with the same folder structure as within mh_omsqlio for each of the files you want to create (thus, if you want callbacks only, you need Classes/Interception/ to exist)
- create **Resources/Private/** folder as we need that in step 3

Step 2: Develop your extended material
--------------------------------------

This means, you create PHP classes for whatever reason and place it in the correct subfolder within Classes. The following folder tree structure shows you where what belongs -- you need to create all the folders on the way to tyour file within your extension's Classes/ directory: ::

    Classes/
        Controller/     <-- main controller that handle data handler
        Data/           <-- handler like Table, Csv, or Detail go here
            Column/     <-- column/field handler like Bool, Rte, TextLong
        Dbal/           <-- abstraction handler to the database (e.g. Mysql)
        Interception/   <-- callbacks and other interceptors (e.g. action handler)
        Transmission/   <-- currently only Json transmitter
        Validation/     <-- form input validators
    Resources/
        Private/
    ext_emconf.php

The file you create has to follow a certain naming pattern for the file and the class (yes, you have to create a class) which start with *Tx_*, followed by the your extension name in upper camel case format, then followed by the folder structure and finally the class name. So imagine a callback (Interception/) in your extension *mh\_omsqlio\_extended* with the name *Tweet*. The file has to be placed and named ::

    Classes/Interception/Tweet.php

And inside the file, the class has to be called: ::

    <?php

        class Tx_MhOmsqlioExtended_Interception_Tweet extends Tx_MhOmsqlio_Interception_Abstract {

            public function callback(
                $_mValue,   //value, how it would be in-/outputted currently
                $_sDir,     //either "in" or "out"
                array $_aData = array(),    //other data of this row (output: database data, input: form data)
                $_bRawOutput = FALSE) {     //true if raw output (e.g. for CSV) is needed

                ...
                return $_mValue;

            }

        }

    ?>

The method inside the function only needs to be called *callback* for callback handlers though. Have a look at the currently existing classes in mh_omsqlio to find other examples.

Step 3: Tell SQL Frontend about your extended material
------------------------------------------------------

Within your new extension create a file within *Resources/Private/* called ::

    extend_mhomsqlio.txt

and fill it with the namespace(s) you are about to modify (one per line). Normally this would do the trick: ::

    Domain/Model/MhOmsqlio

Step 4: Install your own extension
----------------------------------

Navigate to the Extension Manager in your backend, search for the new extension and install it.

Step 5: Clear cache
-------------------

Configuration cache is enough.

Step 6: Use your new handler
----------------------------

That's pretty easy: Within the SQL Frontend's configuration, use the full name of your new class. For instance, our callback configuration would look something like this: ::

    'interception' => array(
        'Callback' => array(
            10 => array(
                'sField' => 'my_column',
                'bInwards' => TRUE,
                'eClass' => 'Tx_MhOmsqlioExtended_Interception_Tweet'
            )
        )
    )