Documentation clarifications (quick-start)

[bitwombat]

Docs for ZF are so good and so essential for the often newbie-mystifying ZF. So I thought I'd seek a few clarifications to the quick start docs.

Happy to work this out and submit a PR once I understand...

From zend-form/quick-start

Item 1:

The chief benefits to using the Factory are allowing you to store definitions in configuration,
and usage of significant whitespace.

"significant whitespace" as in whitespace is significant (a la Python), or there's a significant amount? Either way, "huh"?

Item 2:

The default Form implementation is backed by the Factory. This allows you to extend it,
and define your form internally. This has the benefit of allowing a mixture of programmatic
and factory-backed creation, as well as defining a form for re-use in your application.

What does it mean in OOP or ZF for something to be 'backed by a Factory'? I know what factories are, and how they're used by ZF managers, but as a layman, I see the phrase "This allows you to extend it" and think "But I can extend any non-final class..."

And, many objects implement something like $this->add(), so how does Form being "backed by a Factory" make any difference here?

I think it is important to discuss some of the internals, as knowledge there can help people from being mystified when they 'new' their form in a controller and don't have any access to the usual managers. But some clarification or more explanation is needed for the above.

Thanks for great docs and I hope the above makes sense.

[bitwombat]

For reference:

https://github.com/zendframework/zend-form/blob/master/src/Form.php#L176

Seems to me that the fact that Form uses a $factory is an implementation detail that isn't helpful for understanding how everything works from a user standpoint. $this->add could just as easily be new'ing the elements itself, rather than using a factory.

[froschdesign]

@bitwombat

"and usage of significant whitespace."

I see also no benefit here. I would delete it.

I know what factories are, and how they're used by ZF managers…

But in this context the Form class itself uses a factory. No (service-)manager is required or uses.

"But I can extend any non-final class..."

But that doesn't mean it works. 😉
The overall statement of the paragraph is correct, but a revision of the wording would be helpful for a better understanding.

Seems to me that the fact that Form uses a $factory is an implementation detail that isn't helpful for understanding how everything works from a user standpoint.

This detail is important for understanding how everything works. If you omit this information, then the description how it works is missing.
The quick start already describes the factory and a small notice that the Form class also uses the factory to add elements, doesn't create a confusion.

[bitwombat]

Thanks @froschdesign

So can I nix this sentence?:

"The chief benefits to using the Factory are allowing you to store definitions in configuration, and usage of significant whitespace."

a) because you agree about the whitespace thing, and b) because that benefit is already mentioned above here:

"You can create the entire form and input filter at once using the Factory. This is particularly nice if you want to store your forms as pure configuration; you can then pass the configuration to the factory and be done."

This detail is important for understanding how everything works.

I'm usually a fan, but in this case I'm trying to understand the benefit. Remember, I'm a ZF noob here.

The overall statement of the paragraph is correct, but a revision of the wording would be helpful
for a better understanding.

I think what I may be missing is an understanding of the relationship between all of these guys. Forms extend Fieldsets which extend Elements. And both Forms and Fieldsets comprise Elements...

Ah, looking through the source, the Zend\Form\Factory that is used in the first examples in quick-start is the same factory used by add(). That's what I was missing. Maybe that's obvious, and maybe that's useful? Or not?

As a user, I maybe just want to know that Form::add and Factory::create_form can both take an array of configuration details.

Thanks for the dialog and quick reply.

[weierophinney]

This repository has been closed and moved to laminas/laminas-form; a new issue has been opened at laminas/laminas-form#17.