Diff for TurbaCustomFields between 1 and 2

+ 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 ((Doc/Dev/FormTypes|form field types)) available in the ((Doc/Dev/FormPackage|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.



<code type="php">

// 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
    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
    class Horde_UI_VarRenderer_turba extends Horde_UI_VarRenderer_html {



    //

        // We would likelike to render the input field exactly like a "text"
        // field, so

    // simply call that render method.

    //
        // The _renderVarInput_* methods MUST be implemented.

    function
        function _renderVarInput_image_field($form, &$var, &$vars)

    {

        return
        {
            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
        function _renderVarDisplay_image_field($form, &$var, &$vars)

    {

        return
        {
            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,

);

</code>



In</code>

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.



<code type="php">

$cfgSources['localsql'] = array(

    ...

    'map' => array(

        ...

        'image' => 'object_image',

    ),

    'tabs' => array(

        'Some Tab' => array(..., 'image'),

    ....

</code>



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:



<code type="php">

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

</code>