Re: Your opinion about QuickForm2 API

Bertrand Mansion wrote: > Hi all, > > We are in the middle of a discussion Alexey and I about QuickForm2 API > for elements creation and I would like your opinion as well. > At this point, nothing is immutable since we aren't even talking about > alpha stage, so your preferences as users and developers is interesting. > > To summarize, Alexey would be in favor of this: > > $form->addElement('button', 'aButton', 'Click me please'); > $form->addElement('select', 'aSelect', array('1' => > 'option 1', '2' => > 'option 2')); > > While I would be in favor of this: > > $form->addElement('button', 'aButton')->setContent('Click me > please'); > $form->addElement('select', > 'aSelect')->setOptions(array('1' => 'option > 1', '2' => 'option 2')); > > This is an example for adding a button to a form. The API can get more > complex for Date elements and other javascript aided elements. > > My opinion is that we shouldn't mix configuration parameters for > elements with other kind of data they might need. > > The other point we are discussing is about the extra parameter in > element creation. I suggest we always use an array, even when there is > only one extra parameter. Alexey suggests that we use a scalar if there > is only one extra parameter. For example, for a given "Year" element > which would only accept one configuration parameter 'startYear', Alexey > would use: > > $form->addElement('year', 'aYear', '2007'); > > While I would use: > > $form->addElement('year', 'aYear', array('startYear' => > '2007')); > > So my way is more verbose and less writable, but is also more readable > and extensible. > > Given these examples, are there any opinions or preferences in favor of > one or the other proposed API ? Hi Bertrand, I've honestly found the addElement() API to be difficult to work with in the past, so simplifying it would be a welcome change. However, I don't think "addElement" needs to exist in Quickform2. Have you considered an API similar to the following? <?php $form = new HTML_Quickform2; $form['action'] = '/path/to/action.php'; $form['method'] = 'post'; // or $form['attrs'] = array('action' => '/path/to/action.php', 'method' => 'post'); $g = $form->group['mygroup']; $g->text = array('name' => 'aText', 'size' => 50, 'default' => 'whatever'); $g->select = array('name' => 'aSelect', 'options' => array(...)); // or $g->text(array('name' => 'aText', 'size' => 50)) ->validate['regex'] = '/\w+/'; $g->select(array('name' => 'aSelect', 'options' => array()) $select = $g->select['aSelect']; // or $form->select['aSelect']; $select->options['another'] = 1; $select->validate['custom'] = 'is_numeric'; ?> Compare this to: <?php $form = new HTML_Quickform2('/path/to/action.php', 'method' => 'post'); $form->addGroup('mygroup'); $form->addElement('text', 'aText', array('size' => 50, 'default' => 'whatever', 'group' => 'mygroup') ->validate('regex', '/\w+/'); $sel = $form->addElement('select', 'aSelect', array(...)); $sel->addOption('another', 1); $sel->validate('custom', 'is_numeric'); ?> In the second example, my eyes are drawn to a bunch of "add*" and it appears that the important information ('text', 'select') is secondary. It takes me a while to figure out what is actually being done. The first example has no superfluous information, but simply sets up the form in a straightforward, no-nonsense manner. In other words, I've always dreamed of having a simplexml-like API for accessing/creating forms. I hate translating what I want to do into method APIs. Think of this as bringing the REST model to forms creation, whereas everything has been XML-RPC based up to this point :). Another feature request I've had that may be possible is to integrate some kind of forms creation cache, so that the form need only be created programmatically once, and then it can on subsequent requests be quickly recreated from a disk or database cache, skipping all the expensive method calls, but this is a separate question than the one you asked, let me know if you'd like a feature request opened on this. If you do decide to go with the other API format, I am in favor of more explicit options (associative array/fluent). I hate relying on Zend IDE to do auto-completion, it makes debugging far more difficult to do with just a simple text editor and eyeballs. Greg