Enhanced form element specification

[geekwright]

Re: #453

All aspects of an element can be specified in one invocation. Consider this common scenario:

$buttonCancel = new Xoops\Form\Button('', 'cancel', XoopsLocale::A_CANCEL, 'button');
$buttonCancel->setExtra("onclick='javascript:history.go(-1);'");
$buttonCancel->setClass('btn btn-danger');
$buttonTray->addElement($buttonCancel);

This can all be accomplished with one call:

new Xoops\Form\Button([
    'name' => 'cancel',
    'value' => XoopsLocale::A_CANCEL,
    'type' => 'button',
    'class' => 'btn btn-danger',
    'onclick' => 'javascript:history.go(-1);',
    ':form' => $buttonTray,
]);

This enhanced specification makes it easier to add additional attributes to take advantage of advanced client side features needed in rich web applications. It also simplifies dynamic form generation.

The associative array names are normally HTML attribute names. In some cases, these do not map directly or consistently. For example, Xoops\Form\Elements usually have a 'caption' attribute, but that is not part of the actual HTML input element. The 'value' attribute is usually a normal attribute, but in some cases, such as a TextArea, it is not rendered as an attribute in the tag, but as text enclosed in the tag. These inconsistencies are all handled by the base form classes.

Short form attributes, such as 'required', can be specified with a value of null to render properly.

There is also a special set of attributes known as controls, which affect rendering or operation, but never render directly as attributes. These all begin with a ':'. One example is the ':showdelete' control in the ButtonTray element which specifies if a 'Delete' button should be included. Each class implementing a control documents it in the __construct DocBlock.

Xoops\Form\Element extends Xoops\Html\Attributes which extends \ArrayObject, so all element attributes can be accessed array style if needed, so there is no need for custom getters and setters, which means "no limits!"

There is also a new ElementFactory that can create any element using the enhanced specification. See codex/form-element-factory.php for examples.

In addition, there are a few breaking changes.

• Removed size parameter from DateTime and DateSelect, so signatures are now ($caption, $name, $value) and a reasonable default size is automatically applied. This provides some system wide consistency, and makes these elements easier to work with. (These can still be altered using the enhanced specifications, if desired.)
• In TabTray, the jQueryUI theme parameter was removed, as the theme is controlled by the base assets that can be established by the theme.

Also, the Element::setExtra() method has been deprecated, and will be removed in the future (along with getExtra().) The most common use for this is to add javascript event handlers into the form element. These are much more cleanly implemented using the enhanced specification. For example, this:

$button_2->setExtra("onclick='javascript:window.close();'");

becomes this:

$button_2->set('onclick', 'javascript:window.close();');

which is less convoluted, more comprehensible, and multiple event handlers can be easily specified individually, rather than in a big escape quoted blob.