Proposal for a code documentation

[weierophinney]

I propose to add the following lines to the 'Renderer/PhpRenderer.php' file

* @method \Zend\Form\View\Helper\Form form($form)
 * @method \Zend\Form\View\Helper\FormButton formButton(ElementInterface $element = null, $buttonContent)
 * @method \Zend\Form\View\Helper\FormCaptcha formCaptcha(ElementInterface $element = null)
 * @method \Zend\Form\View\Helper\FormCheckbox formCheckbox(ElementInterface $element = null)
 * @method \Zend\Form\View\Helper\FormCollection formCollection(ElementInterface $element = null, $wrap = true)
 * @method \Zend\Form\View\Helper\FormColor formColor(ElementInterface $element = null)
 * @method \Zend\Form\View\Helper\FormDate formDate(ElementInterface $element = null)
 * @method \Zend\Form\View\Helper\FormDateSelect formDateSelect(ElementInterface $element = null, $dateType = IntlDateFormatter::LONG, $locale = null)
 * @method \Zend\Form\View\Helper\FormDateTime formDateTime(ElementInterface $element = null)
 * @method \Zend\Form\View\Helper\FormDateTimeLocal formDateTimeLocal(ElementInterface $element = null)
 * @method \Zend\Form\View\Helper\FormDateTimeSelect formDateTimeSelect(ElementInterface $element = null,$dateType = IntlDateFormatter::LONG, $timeType = IntlDateFormatter::LONG, $locale = null)
 * @method \Zend\Form\View\Helper\FormElement formElement(ElementInterface $element = null)
 * @method \Zend\Form\View\Helper\FormElementErrors formElementErrors(ElementInterface $element = null, array $attributes = [])
 * @method \Zend\Form\View\Helper\FormEmail formEmail(ElementInterface $element = null)
 * @method \Zend\Form\View\Helper\FormFile formFile(ElementInterface $element = null)
 * @method \Zend\Form\View\Helper\FormHidden formHidden(ElementInterface $element = null)
 * @method \Zend\Form\View\Helper\FormImage formImage(ElementInterface $element = null)
 * @method \Zend\Form\View\Helper\FormInput formInput(ElementInterface $element = null)
 * @method \Zend\Form\View\Helper\FormLabel formLabel(ElementInterface $element = null, $labelContent = null, $position = null)
 * @method \Zend\Form\View\Helper\FormMonth formMonth(ElementInterface $element = null)
 * @method \Zend\Form\View\Helper\FormMonthSelect formMonthSelect(ElementInterface $element = null, $dateType = IntlDateFormatter::LONG, $locale = null)
 * @method \Zend\Form\View\Helper\FormMultiCheckbox formMultiCheckbox(ElementInterface $element = null, $labelPosition = null)
 * @method \Zend\Form\View\Helper\FormNumber formNumber(ElementInterface $element)
 * @method \Zend\Form\View\Helper\FormPassword formPassword(ElementInterface $element)
 * @method \Zend\Form\View\Helper\FormRadio formRadio(ElementInterface $element = null, $labelPosition = null)
 * @method \Zend\Form\View\Helper\FormRange formRange(ElementInterface $element)
 * @method \Zend\Form\View\Helper\FormReset formReset(ElementInterface $element)
 * @method \Zend\Form\View\Helper\FormRow formRow(ElementInterface $element = null, $labelPosition = null, $renderErrors = null, $partial = null)
 * @method \Zend\Form\View\Helper\FormSearch formSearch(ElementInterface $element)
 * @method \Zend\Form\View\Helper\FormSelect formSelect(ElementInterface $element = null)
 * @method \Zend\Form\View\Helper\FormSubmit formSubmit(ElementInterface $element = null)
 * @method \Zend\Form\View\Helper\FormTel formTel(ElementInterface $element = null)
 * @method \Zend\Form\View\Helper\FormText formText(ElementInterface $element = null)
 * @method \Zend\Form\View\Helper\FormTextarea formTextarea(ElementInterface $element = null)
 * @method \Zend\Form\View\Helper\FormTime formTime(ElementInterface $element = null)
 * @method \Zend\Form\View\Helper\FormUrl formUrl(ElementInterface $element = null)
 * @method \Zend\Form\View\Helper\FormWeek formWeek(ElementInterface $element = null)

This will add IDE autocomplete for form helpers

---

Originally posted by @Sohorev at zendframework/zend-view#102

[weierophinney]

It would definitely help, but I see two problems:

• all form helpers do not belong to the Zend\View component
• if we add the form helpers, we must also add the i18n helpers

Are there any other ideas or suggestions how we can get an IDE support for helpers from other components?

---

Originally posted by @froschdesign at zendframework/zend-view#102 (comment)

[weierophinney]

I like the idea to add a description of all the helpers (and i18n helpers too) to the 'Renderer/PhpRenderer.php' file
I have no other ideas. Now for the my project I made a custom renderer in which he described all the helpers

---

Originally posted by @Sohorev at zendframework/zend-view#102 (comment)

[weierophinney]

Agree with @froschdesign. It is also massively misleading, giving impression that the components are already available. I will try to use them, since IDE says they are there, and then get service manager errors about components not existing. This contradictory behavior will not be obvious to solve where the problem is.

It is also a mild problem with custom view helpers.

An off the wall propositions, I hope I won't get stoned for, is to maybe take advantage of composer installer that will automatically add/subtract methods from some interface in a writable directory. Custom view component, or zend\view, can implement interface from somewhere like approot\data\ViewInterface. (needed namespace and autoloading configurations added). As new composer package is installed that has view helpers, it adds another method to that interface. Users of the interface, then have proper up to date knowledge of what is available.

---

Originally posted by @alextech at zendframework/zend-view#102 (comment)

[weierophinney]

Phalcon Framework has additional class-empty structures to help IDE with code completion, called "ide-stubs".

https://github.com/phalcon/ide-stubs

We can create, another project, called "zend-view-stubs", or something, to add this feature into IDEs.

---

Originally posted by @wandersonwhcr at zendframework/zend-view#102 (comment)

[weierophinney]

One thing I did is defining all @method declarations in a trait (one per
module). Not nice, but at least I found a use-case for traits 😋

On 2 May 2017 17:36, "Wanderson Camargo" [email protected] wrote:

Phalcon Framework has additional class-empty structures to help IDE with
code completion, called "ide-stubs".

https://github.com/phalcon/ide-stubs

We can create, another project, called "zend-view-stubs", or something, to
add this feature into IDEs.

—
You are receiving this because you are subscribed to this thread.
Reply to this email directly, view it on GitHub
zendframework/zend-view#102 (comment),
or mute the thread
https://github.com/notifications/unsubscribe-auth/AAJakLvZvlpVJ83DGJ6Wiw_vXt50P8Cqks5r102HgaJpZM4K4-0L
.

---

Originally posted by @Ocramius at zendframework/zend-view#102 (comment)

[weierophinney]

I don't believe you're telling this, @Ocramius! LOL

---

Originally posted by @wandersonwhcr at zendframework/zend-view#102 (comment)

[weierophinney]

I also use traits for zend-form and zend-i18n.

@weierophinney
Any comments on this? Can we create these traits in these components?

---

Originally posted by @froschdesign at zendframework/zend-view#102 (comment)

[weierophinney]

@froschdesign Sure, but the question is: how do these traits then get composed into the PhpRenderer? And if they don't, does that mean the developer is then responsible for creating a sub-class that does? What does that mean for the factory that creates a PhpRenderer instance for the application?

I think there are still questions to be answered...

---

Originally posted by @weierophinney at zendframework/zend-view#102 (comment)

[weierophinney]

@weierophinney
At the moment a user must add on every view scripts these lines:

<?php
/**
 * @var \Zend\View\Renderer\PhpRenderer $this
 */

With the new traits:

<?php
/**
 * @var \Zend\View\Renderer\PhpRenderer|\Zend\Form\View\HelperTrait|\Zend\I18n\View\HelperTrait $this
 */

Depending on which components are in use.

---

Originally posted by @froschdesign at zendframework/zend-view#102 (comment)

[weierophinney]

Oh, I see - the traits go in the view scripts.

Yes, go for it! Don't forget to add documentation for this as well, so folks know what they need to do in order to enable these IDE-centric features.

---

Originally posted by @weierophinney at zendframework/zend-view#102 (comment)

[weierophinney]

@weierophinney

Don't forget to add documentation for this…

We should add an explanation with a code example in the documentation and also a description in the DocBlock of each trait.

---

Originally posted by @froschdesign at zendframework/zend-view#102 (comment)

[weierophinney]

What is the status of this issue?
Are there pull requests associated with this issue in the other repositories?

---

Originally posted by @thexpand at zendframework/zend-view#102 (comment)

[weierophinney]

@thexpand

Are there a pull request associated with this in the other repositories?

No, but the label "help wanted" is still present. 😉

---

Originally posted by @froschdesign at zendframework/zend-view#102 (comment)

[weierophinney]

@froschdesign
I will be able to help, but will need your approval.
As far as I understand, we will need a HelperTrait trait file in every Zend\<COMPONENT>\View namespace that will define all available methods, that the component has, via a @method declaration in the doc block?
Is that correct? If yes, I can make some PRs on the corresponding component repositories.

---

Originally posted by @thexpand at zendframework/zend-view#102 (comment)

[weierophinney]

@thexpand
Correct. The DocBlock of the traits should also include an explanation with a code example how it is used.

---

Originally posted by @froschdesign at zendframework/zend-view#102 (comment)

[weierophinney]

Btw. Thanks in advance. 👍

---

Originally posted by @froschdesign at zendframework/zend-view#102 (comment)

[weierophinney]

@froschdesign
You mean a code example of how the trait is used inside templates?
Such as the second one here: zendframework/zend-view#102 (comment)

---

Originally posted by @thexpand at zendframework/zend-view#102 (comment)

[weierophinney]

@thexpand

You mean a code example of how the trait is used inside templates?

Right, because without any explanation no one knows why these traits are there.

---

Originally posted by @froschdesign at zendframework/zend-view#102 (comment)

[weierophinney]

@froschdesign
Okay, got it. Getting my hands dirty on it ;)

---

Originally posted by @thexpand at zendframework/zend-view#102 (comment)

[froschdesign]

Fixed with #188