Issues

ZF-6151: Translate the title attribute on form buttons including images (FormImage, Submit, Reset, Button)

Description

The title attribute on form elements, specifically buttons, allows for the creation of tooltips.

These tooltips can be very useful, but they need to be translated.

According to the documentation, Zend_Form offers no translation for the title attribute, but I think it would be an improvement if it would.

Obviously, if we are to offer this functionality, the manual needs to be updated accordingly and tests have to be written.

I can write the tests, but I have no experience with changing the manual.

Apart from that, I do not know if there are arguments against translating the attribute or any attributes in general.

I have a sample implementation that works for the FormImage element, but I should also work for submit.


// inside form/element/Image.php
    /**
     * Set the title (tooltip) for the image button. The tooltip will be translated if a translator
     * is available and not disabled.
     *
     * @param string $title
     * @return provides a fluent interface
     */
    public function setTitle($title)
    {
        // translate title (tooltip)
        if (!$this->_translatorDisabled and null !== ($translator = $this->getTranslator())) {
            $title = $translator->translate($title);
        }
        
        $this->setAttrib('title', $title);
        return $this;
    }

If it is to work for submit and reset this function has to inside /form/Element.php with slightly simple comments:


    /**
     * Set the title (tooltip). The tooltip will be translated if a translator
     * is available and not disabled.
     *
     * @param string $title
     * @return provides a fluent interface
     */
    public function setTitle($title)
    {
        if (!$this->_translatorDisabled and null !== ($translator = $this->getTranslator())) {
            $title = $translator->translate($title);
        }
        
        $this->setAttrib('title', $title);
        return $this;
    }

The drawback of these is that setDisableTranslator() will have no effect if it is called after setTitle or if 'title' is passed in as an option before.

The only other way I tried so far, was to put this functionality in the render method, so that normal behavior of setDisableTranslator() and getAttrib('title') are ensured. The latter should always return the untranslated version, but it will not if we use the naive implementation listed above.

The drawback of translating in the render method is that we would impact all form elements performance wise, with a check for the presence of a title attribute. With large forms this impact will be considerable and very wasteful as most elements will not have title attributes and will not require translation of this attribute.

Therefore I think one way to offer this is to create a common base class for elements that can have tooltips. However, this is not the way Zend Framework works in general. On the contrary, we try to avoid this. The way to go would be to create an new decorator, that translates the tooltip. This would be a tooltip decorator. Is it already here and have I been missing it all along? No luckily, it looks like it is not yet there.

Then adding such a decorator manually would be more work then just translate the title attribute manually while passing it in... so I should be looking for a way to add this decorator to those elements that can benefit from it, like image, submit and reset. The best place for this will be loadDefaultDecorators().

Inside Zend_Form_Element_Submit.php:


    /**
     * Default decorators
     *
     * Uses only 'Tooltip',  'Submit' and 'DtDdWrapper' decorators by default.
     * 
     * @return void
     */
    public function loadDefaultDecorators()
    {
        if ($this->loadDefaultDecoratorsIsDisabled()) {
            return;
        }

        $decorators = $this->getDecorators();
        if (empty($decorators)) {
            $this->addDecorator('Tooltip')
                 ->addDecorator('ViewHelper')
                 ->addDecorator('DtDdWrapper');
        }
    }

This works indeed. It required a new decorator: Zend_Form_Decorator_Tooltip and it requires Zend_Form_Element_Submit and Zend_Form_Element_Image to load this decorator as the first decorator in loadDefaultDecorators(). This is not a problem since the decorator doesn't add any output, only translates the title attribute when the element is rendered.

I will attach my proposal for Zend_Form_Decorator_Tooltip.

If I receive no negative feedback, I will add two unit tests that will test the following: 1. Does the title get translated if a translation is present 2. Does the title remain unchanged when the translator is disabled

Like I said before, I have no experience in updating the manual. I would appreciate it very much if Matthew or someone else would take care of that bit.

Comments

Zend_Form_Decorator_Tooltip proposal attached.

Added two unit tests in TestImage.php and TestSubmit.php. These also cover Reset and Button, as these inherit from Submit.

Added new Zend_Form_Decorator_Tooltip and load it in both Submit and Image in loadDefaultDecorators().

All is in svn now as I have not received any negative feedback on this from the community.

What is left to do now is add a line to the manual telling that the title is now being translated on buttons.