override decorators

Overriding form decorators

Garp_Form adds a couple of default decorators to every element: ViewHelper, Label, Description, Errors and HtmlTag. These provide a sensible default for displaying form elements.

It will never overwrite decorators supplied by the user though, so anytime you add the key decorators to the $options array, the default decorators won't be added.

A downside to this is that it's very hard to make a small adjustment to a default decorator, but keep the rest intact. This requires you to always supply the full list of default decorators, or modify the decorators after adding the element, using $form->getElement('foo')->getDecorator('bar')->setOption().

Luckily, Garp_Form looks for a specific option called inherit to bind certain merge/overwrite patterns.

Merge decorator options

The following sets the escape option of the default Label decorator, but keeps the rest as is:

$form->addElement(
    'text', 'foo', [
        'decorators' => [
            'inherit' => [
                'merge_options' => [
                    ['Label', ['escape' => false]]
                ]
            ]
        ]
    ]
);

Omitting a single default decorator

This removes the Description decorator, but leaves the rest alone:

$form->addElement(
    'text', 'foo', [
        'decorators' => [
            'inherit' => [
                'omit' => [
                    'Description'
                ]
            ]
        ]
    ]
);

Merge a decorator into the list of default decorators

This inserts the Captcha decorator into the list, before the Errors decorator:

$form->addElement(
    'text', 'foo', [
        'decorators' => [
            'inherit' => [
                'merge' => [
                    [
                        'at' => 'Errors',
                        'spec' => ['Captcha']
                    ]
                ]
            ]
        ]
    ]
);

This inserts the Captcha decorator into the list, after the Errors decorator:

$form->addElement(
    'text', 'foo', [
        'decorators' => [
            'inherit' => [
                'merge' => [
                    [
                        'after' => 'Errors',
                        'spec' => ['Captcha']
                    ]
                ]
            ]
        ]
    ]
);

This appends the Captcha decorator to the list:

$form->addElement(
    'text', 'foo', [
        'decorators' => [
            'inherit' => [
                'merge' => [
                    [
                        'Captcha'
                    ]
                ]
            ]
        ]
    ]
);