[meta] Move/Create Form Element Documentation

It looks like all the existing child issues have been completed, but I think that there are probably more groups of form/render elements that need documentation still?

I took a look at the classes in
core/lib/Drupal/Core/Render/Element/
to see which ones still need improved docs. I think this is the list... maybe not all of them need docs (this was a quick scan) but they bear another look at least:

Ajax
File
Form
Html
HtmlTag
ImageButton
InlineTemplate
Item
Label
LanguageSelect
Link
MoreLink
Operations
Page
PageTitle
Pager
PathElement
StatusMessages
SubmitCompactLink
Token

Form - yeah, well. So this is only set in FormBuilder::prepareForm(). However, it is pretty common for individual form-generating methods (implementations of FormInterface::buildForm() ) to set various properties of the outer form array. So I would think we should document those properties (the old FAPI reference should list them).

Operations, Token - agreed, sorry for including those. Too quick of a look. :(

SubmitCompactLink - oops. I meant SystemCompactLink. Adding this to your new Render issue.

Html/Page/PageTitle - agreed those are used internally by Drupal to render the page. Let's just mention that in their docs. Added issue for that, and ... well I will put Form on there too.
#2599784: Document Form, Html, Page, and PageTitle Elements

Also I should mention, if you didn't see it in the sidebar, that I created an issue for documenting the standard shared form/render properties: #2599442: Document common form/render element properties

Great! So now we have issues for all the remaining ones in the main directory there... may need to document a few more living in core modules, and I'll check on that shortly.

Oh. I was also going to tell you that I showed off some of the output of your recent patches at BADCamp and everyone seemed very happy with (a) the results and (b) the maintainability of having the docs there. So THANKS metzlerd!

And see also #2596821: Make an "Elements" listing page, which will make a page listing all of those elements, once it is deployed to api.drupal.org; also I did #839550: Ability to add documentation headers to global listing pages (Classes, Functions, etc.), which will let us put a documentation header on that page. Woot! Yeah BADCamp!

So what about \Drupal\Core\Render\Element\Date ?

Personally I think this issue should be Critical, because I see it as unacceptable to release 8.0 without a complete list of form elements along with documentation for each.

The release cycle is pretty much set in stone at the moment, though code style and documentation changes can happen. Upping the priority would be counter productive at this point.

There's an accompanying form_example being put together mainly by @Metzlerd, over in the Examples project, which has a little more latitude with the documentation and code samples: #2102659: Add new Form API example module for Drupal 8

I'm going to see if I can get the API module changes that make a list of these elements up on api.drupal.org in the next few days too.

@Mile23: Yes, I'm sure it will expedite the release of 8.0 if long-standing issues are swept under the rug.

Right now form elements aren't documented, and that has been a problem for years. Previous issues were recently closed as duplicates in favor of this current issue. Some previous issues have been MAJOR, so this is a downgrade of the importance. In addition, closing those issues has hidden all the previous input and concerns that have been raised.

As a developer, I currently have no idea what form elements are allowed and what their required/optional parameters are.

@metzlerd: Apparently Date was meant to be internal and doesn't work as a stand-alone element. See the details at https://www.drupal.org/node/2528482#comment-10145050 . While using #type = 'date' doesn't cause a PHP notice anymore, it still doesn't work as expected.

Documentation is important not only for contrib developers, but also for core developers - if there is no documentation then there is nothing to test to make sure it works as designed.

@TR: I am a bit bewildered by your statement that "Form elements are not documented", which seems to be mostly based on problems you have identified in the Date element documentation. If there's an issue about the Date element documentation, by all means please file an issue and let's get it fixed. You seem to know more about it than those of us who patched, reviewed, and committed the issues where the Date element class and the other classes were documented, which is too bad. But the nice thing about documentation is that it is not set in stone -- if we make an issue and a patch, we can still fix it. A devoted issue saying what we need to do to fix that Date documentation would be very helpful, so that we can make it correct -- could you please file one and mark it as having this one as a parent so it doesn't get lost? Thanks!

As far as having a list of all elements, yes we definitely need one, and I've been working on it. It should be on api.drupal.org ... later today or tomorrow.

I also think that the more common elements, like Checkboxes etc., are pretty well documented now, and we also have documentation for the standard form/element properties on
https://api.drupal.org/api/drupal/core!lib!Drupal!Core!Render!Element!Re...
https://api.drupal.org/api/drupal/core!lib!Drupal!Core!Render!Element!Fo...
as of a few days ago.

And there are also two topics that cover form and render arrays:
https://api.drupal.org/api/drupal/core!lib!Drupal!Core!Render!theme.api....
https://api.drupal.org/api/drupal/core!core.api.php/group/form_api/8

So... If after reading all of that, you find that there are things that haven't been documented, please rather than just complaining that "it's not documented", file specific issues and we'll get it documented. Documentation issues don't block release, and can be fixed after release. So let's at least make sure the issues get filed for problems or lacks that exist, and we'll eventually get them done. Thanks!

So... the list of form/render elements is now being built on api.drupal.org -- it should be complete in an hour or two at:
https://api.drupal.org/api/drupal/elements/8
Hm. I think it's mostly there now.

On #2603818: Add defgroups for listing page headers for api.drupal.org I have a patch that will add a documentation header to that page (as well as the Classes, Namespaces, and Services listing pages). A review of that patch would be greatly appreciated, and would further the cause of having documentation available. Thanks!

Can someone make a redirect from this page

https://api.drupal.org/api/drupal/developer!topics!forms_api_reference.h...

to

https://api.drupal.org/api/drupal/elements/8

A lot of people coming from Google..
And I personally find the old format easier to navigate than the new one.

Sorry that you prefer the old format, but it was a very outdated document because it was nearly impossible to maintain.

I'll file an issue to get the redirect done, which we meant to do and forgot -- sorry about that.
#2671300: Add redirect for D8 form api reference

Yes, we should link that to https://api.drupal.org/api/drupal/elements

I thought we had already done so but apparently not.

We need to get back to this. Someone just created an issue and I added it as a child of this one:
#3157135: Properties of Form FormElement are missing

This issue is still open too:
#2599742: Document several form elements that have no docs

So I think we need to go through all of the elements on
https://api.drupal.org/api/drupal/elements/9.0.x
and see which ones still need documentation, make issues for them, and fix them.

Today I went through all of the elements on
https://api.drupal.org/api/drupal/elements/9.0.x
I clicked through to each class, and looked to see if the class had documentation on Properties and a Usage Example. I did not verify that the property documentation was correct or complete. I skipped a couple whose documentation said they were for internal use during rendering, like Label and Radio.

The following classes are missing Properties and Usage Example, and should probably have them added (there may be a few that don't have special properties and don't need additional docs, but I think most of these do):
core/lib/Drupal/Core/Render/Element/Ajax.php
core/modules/contextual/src/Element/ContextualLinks.php
core/modules/contextual/src/Element/ContextualLinksPlaceholder.php
core/lib/Drupal/Core/Datetime/Element/Datelist.php
core/lib/Drupal/Core/Datetime/Element/Datetime.php
core/lib/Drupal/Core/Entity/Element/EntityAutocomplete.php
core/modules/field_ui/src/Element/FieldUiTable.php
core/lib/Drupal/Core/Render/Element/Fieldgroup.php
core/lib/Drupal/Core/Render/Element/Fieldset.php
core/lib/Drupal/Core/Render/Element/Form.php
core/lib/Drupal/Core/Render/Element/Html.php
core/lib/Drupal/Core/Render/Element/ImageButton.php
core/lib/Drupal/Core/Render/Element/Item.php
core/modules/language/src/Element/LanguageConfiguration.php
core/lib/Drupal/Core/Render/Element/LanguageSelect.php
core/modules/file/src/Element/ManagedFile.php
core/lib/Drupal/Core/Render/Element/Page.php
core/lib/Drupal/Core/Render/Element/PageTitle.php
core/lib/Drupal/Core/Render/Element/PathElement.php
core/modules/filter/src/Element/ProcessedText.php
core/modules/responsive_image/src/Element/ResponsiveImage.php
core/lib/Drupal/Core/Render/Element/Search.php
core/lib/Drupal/Core/Render/Element/StatusReport.php
core/modules/system/src/Element/StatusReportPage.php
core/lib/Drupal/Core/Render/Element/Token.php
core/modules/toolbar/src/Element/Toolbar.php
core/modules/toolbar/src/Element/ToolbarItem.php
core/modules/views/src/Element/View.php

Some of these elements are already on child issues:
#2599784: Document Form, Html, Page, and PageTitle Elements
#2599742: Document several form elements that have no docs

I made a new child issue for the rest of them:
#3157885: Document a bunch of render elements

Hi! I've checked all properties of Elements from web/core/lib/Drupal/Core/Render/Element folder to found which of them are missed in documentation. Maybe, some properties description was already added in issues, nevertheless, I hope attached report is correct and will be useful.

Thanks for doing that!

I'm a bit confused though. I started with Button. Your document lists these properties as not being documented:

‘#limit_validation_errors’
'#value'
'#name'
'#executes_submit_callback'
'#submit' 
'#widget_id' 

But when I go to the Button class:
https://api.drupal.org/api/drupal/core%21lib%21Drupal%21Core%21Render%21...
that page documents both limit_validation_errors and value... so those should not be in your list.

widget_id... Where did that come from? It doesn't seem like that is a property of Button? I can't see that it uses the submit property either?

I didn't get past Button because I didn't understand the results there.

Also to think about: some of the properties you listed might be for internal use only during the rendering process. We really only want to doucment the properties that someone who is using the form/render element in a render array would need to know about.

Thanks @jhodgdon.
You are right, of course. Seems for Button are missed only 3 properties:

Button extends FormElement

'#name'
'#executes_submit_callback'
'#submit' 

Also to think about: some of the properties you listed might be for internal use only during the rendering process. We really only want to doucment the properties that someone who is using the form/render element in a render array would need to know about.

- Ok, it really make sense. Not sure, that I can confidently differentiate which of these properties are for internal use only.
So, I just searched in core this elements properties and made a list all that are not mentioned in web/core/lib/Drupal/Core/Render/Element/RenderElement.php, web/core/lib/Drupal/Core/Render/Element/FormElement.php,
or directly in the appropriate element class. I apologise in advance for the inaccuracies, I will correct if possible, and I've attached updated list.

@jhodgdon, maybe it will be more helpful to have editable list, so I've attached txt. If you wish, you can help to remove internal properties from it.

OK, this is better...

So it seems to me that we should document the following properties on the FormElement class:
#validate
#submit
#executes_submit_callback

#name
#value

#error_no_message

We should probably go through the FormBuilder, FormElement, and FormValidator classes, and inline_Form_errors.module, and see if there are any other common properties for forms that are implicit in building, validating, and error handling that we've missed.

Also... I'm wondering where your list came from? Because there are still properties that you've listed that I have no idea why you think they are properties of those particular elements? For instance, anything with "test" on it is probably suspect, such as #form-test_required_error. Just because someone has used a particular element in a test with a particular property doesn't mean it is actually a property that the element supports. We only want to document the supported properties. Tests often do weird things.

Ok, all with "test" in this list should be ignored, thank you for explanation!

But the question still remains, where did the other items come from that you think should be documented?

@jhodgdon I looked throw core/ folder predominantly, but maybe some properties were in contrib modules and as you said they can be used only in that particular cases. I've removed all extra modules from my clean D8 installation already. So, let me re-check.

And some examples:
InlineTemplate - '#cell_attributes' used here web/core/modules/field_ui/src/Form/EntityDisplayFormBase.php, buildFieldRow()
Number - '#maxlength' in web/core/modules/editor/editor.admin.inc, editor_image_upload_settings_form()
Radio - '#return_value' in web/core/modules/views/src/Plugin/views/argument/ArgumentPluginBase.php, processContainerRadios()

Maybe this is also some specific cases? I just wanted to have list of all available properties as we have in D7

Yeah, sometimes particular uses of templates would add properties that are specific to their use, especially if they override a theme template. So I think we should only document properties that we can verify are actually handled by the Element class, its default theme template and preprocessing, the FormBuilder and FormValidator classes, and the RenderElement and FormElement base classes.

That is how we decided which properties to document the first time around. Unfortunately:
- Not all elements got documented (there are still open issues)
- Since we did that, additional properties were added and as usual, no one bothered to update documentation.

So... I think what you've done is a useful first step, but we will still have to verify that the properties are part of the base functionality, and also if they are, decide where to document them (which could be on the specific element class or the RenderElement or FormElement base class). Probably for now it is not worth the time to pare down your list to just Core -- probably you don't have too many extras... but you might also not have all of the properties that are supported (it's possible they are never used in a Form or Render array in Core).

Hello, me and some colleagues are working on improving/creating documentation both on wiki and API on this meta issue.

For me, the most important missing documentation is that we need a Drupal 10/11 version of the Drupal 7 "Form API Reference" page. Perhaps this is done as more than one page, but somewhere there needs to be list of valid values for #type and a way to find out what properties can be used with each type.