Re: Your opinion about QuickForm2 API

On 4/16/07, Bertrand Mansion <golgote@mamasam.com> 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'));

Well, this has worked in the past and isn't too hard to grasp if the documentation makes it clear how this works (the current docs are a bit confusing in this regard). Having the additional parameters be the constructor args for the element is a fine option. However, it's always confusing to have lots of parameters to a method and I know I never remember which is which.

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.

While this *is* more OO-like I don't see the utility in making the call directly like this. It seems more hack-y to me and doesn't take into account the cases where you want to set 2 or more parameters. You *could* have all option-setting methods return $this but that seems like a major hack to me and will only make for really long chains of possibly confusing code. If you feel like going the method way I'd suggest either having people use a temp var or a get function. $el = $form->addElement('button', 'aButton'); $el->setContent('Click me please'); Then put the above in as a "you can also do it this way if you only want to set one option" tip.

My opinion is that we shouldn't mix configuration parameters for elements with other kind of data they might need.

I'm sorry, I don't understand the distinction here. IMHO everything that is currently being passed to an element is needed data for the element to be useful. It doesn't really make sense to just: $form->addElement('button', 'aButton'); as the element will be incomplete.

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.

Extensability is a good thing. Readability is a good thing. I'd vote for an assoc array over variable numbers of arguments.

Given these examples, are there any opinions or preferences in favor of one or the other proposed API ? Thanks in advance,

While I think that the functions should of course also be usable to do the OO-style setting I prefer being able to set all of the relevant configuration values via addElement with an assoc array. -- Justin Patrin