Your opinion about QuickForm2 API

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 ?
Thanks in advance,


--
Bertrand Mansion
Mamasam
Work : http://www.mamasam.com
Blog : http://golgote.freeflux.n
et

-- 
PEAR Development Mailing List (http://pear.php.net/)
To unsubscribe, visit: http://www.php.net/unsub
.php

Bertrand Mansion wrote:
> 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'));

This is the old (and IMO sometimes confusing) style which is
(at least
in the current QF) not consistent through the various
elements.

> 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 style is more "OO-ish" (*g*) and should also
be more consistent in
usage.

+1, therefore

[...]
> 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'));

+1 for this last style because it avoids confusion, too, and
especially
also because sometimes later such elements might get a
second, third,
... option.

Regards,
Mark


X'Post: php.pear.dev,php.pear.general
-- 
http://www.markwiesemann.
eu

-- 
PEAR Development Mailing List (http://pear.php.net/)
To unsubscribe, visit: http://www.php.net/unsub
.php

Bertrand Mansion ha scritto:
> 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'));
>
-1 confusing, as in current QF release.
> 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'));
>
+1 more clean
> 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');
>
-1 confusing
> 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.
>
+1 lesse writeable but very standard.
> Given these examples, are there any opinions or
preferences in favor 
> of one or the other proposed API ?
> Thanks in advance,
>
>
> -- 
> Bertrand Mansion
> Mamasam
> Work : http://www.mamasam.com
> Blog : http://golgote.freeflux.n
et
>
> --PEAR Development Mailing List (http://pear.php.net/)
> To unsubscribe, visit: http://www.php.net/unsub
.php
>
>

-- 
PEAR Development Mailing List (http://pear.php.net/)
To unsubscribe, visit: http://www.php.net/unsub
.php

Hi,

Bertrand Mansion wrote:
> 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.

I'd like to clarify a bit: both of the above calls are
possible right now, see 
the relevant elements
htt
p://cvs.php.net/viewvc.cgi/pear/HTML_QuickForm2/QuickForm2/E
lement/Button.php?revision=1.1&view=markup
htt
p://cvs.php.net/viewvc.cgi/pear/HTML_QuickForm2/QuickForm2/E
lement/Select.php?revision=1.4&view=markup

So this is just an issue of personal preference, which isn't
being enforced or 
something.

What's really being discussed is the following, will we make
the "additional 
data" parameter that has different semantics from
element to element always an 
array, so the first pair of calls above turns into

$form->addElement('button', 'aButton', array('content'
=> 'Click me please'));
$form->addElement('select', 'aSelect', array('options'
=> array('1' => 'option 
1', '2' => 'option 2')));

even though the elements in question will never need any
additional data other 
than 'content' and 'options'.

> 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 ?
> Thanks in advance,

-- 
PEAR Development Mailing List (http://pear.php.net/)
To unsubscribe, visit: http://www.php.net/unsub
.php

On 4/16/07, Alexey Borzov <borz_offcs.msu.su> wrote:
> Hi,
>
> Bertrand Mansion wrote:
> > 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.
>
> I'd like to clarify a bit: both of the above calls are
possible right now, see
> the relevant elements
> htt
p://cvs.php.net/viewvc.cgi/pear/HTML_QuickForm2/QuickForm2/E
lement/Button.php?revision=1.1&view=markup
> htt
p://cvs.php.net/viewvc.cgi/pear/HTML_QuickForm2/QuickForm2/E
lement/Select.php?revision=1.4&view=markup
>
> So this is just an issue of personal preference, which
isn't being enforced or
> something.
>
> What's really being discussed is the following, will we
make the "additional
> data" parameter that has different semantics from
element to element always an
> array, so the first pair of calls above turns into
>
> $form->addElement('button', 'aButton',
array('content' => 'Click me please'));
> $form->addElement('select', 'aSelect',
array('options' => array('1' => 'option
> 1', '2' => 'option 2')));
>
> even though the elements in question will never need
any additional data other
> than 'content' and 'options'.
>

'will we make the "additional data" parameter that
has different
semantics from element to element always an array,'

+1 for this

My vote would be for always an array --- even in cases where
an
element will only need one piece of scalar data.

As many have already pointed out, changing from scalars to
array based
on the individual element leads to confusion about which
elements
require which parameter format --- I would even be against
the
flexibility of allowing both ways because I think it leads
to more
complicated documentation and more room for coding errors.

-- 
-Brett Bieber

http:saltybeagle.com aim:ianswerq

-- 
PEAR Development Mailing List (http://pear.php.net/)
To unsubscribe, visit: http://www.php.net/unsub
.php

I haven't been working with QuickForm, PEAR, or even PHP
very long 
(though I'm a veteran of other non-web languages), so take
my opinion 
likely, but I prefer Bertrand's syntax.  I find the concept
whereby 
parameters can having multiple different meanings confusing.
 I like the 
clarity of Bertrand's proposals, even if it might not seem
as 'terse' as 
Alexey's options.

On Mon, Apr 16, 2007 at 11:08:16AM +0200, 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 ?
>Thanks in advance,

-- 
PEAR Development Mailing List (http://pear.php.net/)
To unsubscribe, visit: http://www.php.net/unsub
.php

On 4/16/07, Bertrand Mansion <golgotemamasam.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

-- 
PEAR Development Mailing List (http://pear.php.net/)
To unsubscribe, visit: http://www.php.net/unsub
.php

Le 16 avr. 07 à 16:59, Justin Patrin a écrit :

> On 4/16/07, Bertrand Mansion <golgotemamasam.com> wrote:
>> 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.

This is called "Fluent interfaces" and is not a
major hack 

ht
tp://martinfowler.com/bliki/FluentInterface.html
http://www.m
ikenaberezny.com/archives/35


--
Bertrand Mansion
Mamasam
Work : http://www.mamasam.com
Blog : http://golgote.freeflux.n
et

--
PEAR Development Mailing List (http://pear.php.net/)
To unsubscribe, visit: http://www.php.net/unsub
.php

On 4/16/07, Bertrand Mansion <golgotemamasam.com> wrote:
>
> Le 16 avr. 07 à 16:59, Justin Patrin a écrit :
>
> > On 4/16/07, Bertrand Mansion <golgotemamasam.com> wrote:
> >> 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.
>
> This is called "Fluent interfaces" and is not
a major hack 
>

+1 defenatly
> ht
tp://martinfowler.com/bliki/FluentInterface.html
> http://www.m
ikenaberezny.com/archives/35
>
>
> --
> Bertrand Mansion
> Mamasam
> Work : http://www.mamasam.com
> Blog : http://golgote.freeflux.n
et
>
> --
> PEAR Development Mailing List (http://pear.php.net/)
> To unsubscribe, visit: http://www.php.net/unsub
.php
>
>

+1 overall idea, however we will need end user
documentation, we
should not forget that 

-- 
David Coallier,
Founder & Software Architect,
Agora Production (http://agoraproduction.com
)
51.42.06.70.18

--
PEAR Development Mailing List (http://pear.php.net/)
To unsubscribe, visit: http://www.php.net/unsub
.php

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

-- 
PEAR Development Mailing List (http://pear.php.net/)
To unsubscribe, visit: http://www.php.net/unsub
.php