Re: Learning PEAR

Hi! Keith Edmunds wrote:

We can start with the section "Introduction - renderers", which asks the question "What are renderers?" but never answers it. The closest we get is when we learn that "The form output logic is now contained in classes that extend HTML_QuickForm_Renderer" - how does that help me?

OK, here is the answer: "The renderers are the classes that contain specific form output logic". Better now? :]

What does HTML_QuickForm_Renderer do? Then I'm told that "There are 5 renderers currently available, of which 2 are based on pre-3.0 code and 3 are new." What are their names? Where can I find out more about them?

Look down a bit... Yes, here they are: HTML_QuickForm_Renderer_Default HTML_QuickForm_Renderer_Array HTML_QuickForm_Renderer_ArraySmarty HTML_QuickForm_Renderer_ITDynamic HTML_QuickForm_Renderer_ITStatic

Does it matter that two are based on pre-3.0 code and, if so, how does it matter?

It matters to those who were using pre-3.0 QuickForm. My sincere apologies that it does not matter to *you*.

Which of these five should I be using? How do I choose?

You do know whether you are using a template engine? If yes, you do know its name? If you haven't yet decided, here are some quotes to help: http://pear.php.net/manual/en/package.html.html-quickform.html-quickform-renderer-default.php "It is recommended to use the Deault renderer when you are not using any template engine in your application or do not need to do any customization to form output. It is the fastest way to output a form." http://pear.php.net/manual/en/package.html.html-quickform.html-quickform-renderer-itdynamic.php "If most of your forms tend to share the same look (a good example would be back-office interface), your best bet will be to use Dynamic renderer. If each of your forms has a really special layout, you should go with a Static one." http://pear.php.net/manual/en/package.html.html-quickform.html-quickform-renderer-itstatic.php "The IT Static renderer, as opposed to the IT Dynamic renderer, offers more flexibility in the way you display your forms but might also takes more time to implement. Therefore, if your form is using always the same pattern to display form element labels and form element html, it is recommended to use the Dynamic renderer. On the other hand, if you have many different layouts for your form elements, for example if you alternate text and form elements, you will prefer to use the Static renderer."

I don't mean to pick on Quickform in particular - that's just what I have been tearing my hair out over today (and I have precious little hair to spare).

I don't mean to be rude, but renderers are the better documented part of QuickForm. And you *obviously* didn't read the chapter on them past the introduction or looked at the examples provided in the package.

Statements such as (HTML_QuickForm::addElement()) "If $element is a string representing an element type, then this method accepts variable number of parameters, their meaning and count depending on element type" are NOT sufficient - people just aren't going to figure out where the source file is and read it just to find out what the arguments for adding a textarea are.

Wow! The first *real* problem. Yes, the API docs for element classes are lacking. But if you think that your message motivates me to write them, think again. Besides, the problem with QuickForm is that it is BIG. And the problem with PEAR's doc infrastructure is that it is not suited for big packages: * I added subsections to QuickForm summary page and navigation became fucked up as it is capable of managing only one level. * The TOCs are plain, not hierarchical I suspect that if we add docs for all the elements, the page will be unreadable. And I reckon reading that there is no one in PEAR who can actually fix the DSSSL stylesheets for the docs.

All comments above meant to be constructive: I'm still prepared to help where I can.

OK, what missing part of QuickForm documentation would you like to write? I suggest a tutorial on groups usage.