6.0.0-git
2024-03-19
Last Modified 2008-07-05 by Jan Schneider

Creating and using custom field types in Turba

Turba already ships with a huge number of available attributes, and you can even create more attributes simply by adding new entries to config/attributes.php. If you create new attributes you can choose from the large number of form field types available in the Horde_Form library. If this still doesn't provide you with the form fields that you want to add to your Turba address book, you have to create your own field types. This is what this Howto is about.

Creating form and renderer classes

All the code you add should go into config/attributes.php because this file is loaded on each page request so we can be sure that the classes that we are going to add are always available. Beside that, it's a configuration file, so it will never get overwritten by any Turba upgrade.

In the following example we are going to add a field where users can add an image URL, and have this image rendered in the contact view. Not very useful, but simple enough for demonstration purposes.

// Load all required libraries.
require_once 'Horde/Form.php';
require_once 'Horde/UI/VarRenderer.php';
require_once 'Horde/UI/VarRenderer/html.php';

if (!class_exists('Horde_Form_Type_image_field')) {
    // In this example simply inherit from the "text" field type.
    class Horde_Form_Type_image_field extends Horde_Form_Type_text {}

    // The only renderer currently available (as of Horde 3.2) is the "html"
    // renderer, so we inherit from that.
    class Horde_UI_VarRenderer_turba extends Horde_UI_VarRenderer_html {

        // We would like to render the input field exactly like a "text"
        // field, so simply call that render method.
        // The _renderVarInput_* methods MUST be implemented.
        function _renderVarInput_image_field($form, &$var, &$vars)
        {
            return $this->_renderVarInput_text($form, $var, $vars);
        }

        // The display of the field should be rendered as an image tag.
        // The _renderVarDisplay_* methods are OPTIONAL.
        function _renderVarDisplay_image_field($form, &$var, &$vars)
        {
            return '<img src="' . htmlspecialchars($var->getValue($vars)) . '" />';
        }
    }

}

// Define an attribute that uses our new field type called "image_field".
$attributes['image'] = array(
    'label' => 'Image',
    'type' => 'image_field',
    'required' => false,
);

In this example we inherit from the "text" field type. That means that the new field accepts the same parameters like a "text" field. You can inherit from any other existing form field, or even from Horde_Form_Type directly. If you inherit, you can overwrite any existing property or method of the parent class. Take a look at all the different type classes in framework/Form/Form.php or lib/Horde/Form.php.

Now you need to use the new attribute in your address book, by adding it to your source definition. Of course you also need a field in the storage backend where the contents of the field can be stored. You have to add the attribute to the 'map' list, and to the 'tabs' list, if one exists.

$cfgSources['localsql'] = array(
    ...
    'map' => array(
        ...
        'image' => 'object_image',
    ),
    'tabs' => array(
        'Some Tab' => array(..., 'image'),
    ....

Finally you need to change some code in Turba to actually use the renderer that you earlier created in attributes.php. For Turba 1.2.x these are the files lib/Views/EditContact.php and lib/Views/Contact.php. These are the only places where original code has to be patched. Search in both files for calls to the Horde_Form_Renderer() constructor and add an parameter so that the look like:

new Horde_Form_Renderer(array('varrenderer_driver' => 'turba'))