[cvs] [Wiki] created: TurbaCustomFields

[Jan Schneider]

jan  Fri, 04 Jul 2008 17:11:29 -0400

Created page: http://wiki.horde.org/TurbaCustomFields

+ 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';

// 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,
);
</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>