Fieldsets vs. Details: When to use what and why?

The current handbook page about Fieldsets can probably be renamed to "Details", and be slightly adjusted.

The nice thing about the details element is that its name already encompasses and clarifies what it is about: details. ;) Most of that current Fieldset documentation page goes to great lengths in trying to describe that it's meant for grouping... details. :)

We need a new handbook page for Fieldsets though. The accessibility team wants to make #504962: Provide a compound form element with accessible labels happen, and they believe that fieldsets should not be used for anything else than that. I yet have to double-check the HTML spec for whether that claim is correct.

Lastly, we're currently working on #1829202: Make #type 'item' work outside of a form context to render a compound label + content, and it looks like we're going to revise and merge #type 'item' into a more sophisticated #type 'container', which can have an optional label/heading/#title.

Assuming that will happen, we'd end up with the following:

1. #type details for collapsible details (advanced information or form-controls/settings).
2. #type container for grouping markup elements into a container, optionally with label/heading.
3. #type fieldset for (invisibly) grouping compound form elements.

Well, it's a start but I added a Details page here - http://drupal.org/node/1898824

We can't just rename the Fieldset page as for D7 it is still going to be relevant. I did just copy the content & start adjusting from there though.

Are there other examples of handbook pages that have different instructions for different versions of Drupal?

I don't think that the html specs are as clear as we'd like:
http://www.w3.org/wiki/HTML/Elements/fieldset

There have been reports of embedding fieldsets within each other. I haven't verified this. We'd like radios, checkboxes, height/width & any other multi-part form to have a fieldset in D8 and this has been a challenge historically.

Some info about this from an accessibility point of view is here:
http://webaim.org/techniques/forms/screen_reader#group

Anyways, glad we've got a place now to start documenting this. A first rough, rough draft.

EDIT - We definitely need to change the screen shot of the details page when we're closer to release. I expect it might change and best to just do it once. Fieldset gets the point across visually I think.

The details form element also needs documentation in the Form API docs. In other words, https://api.drupal.org/api/drupal/developer%21topics%21forms_api_reference.html/8#detail needs to go somewhere. I'd love to provide a patch but I have no idea how that file is generated.

Any pointers?

http://drupalcode.org/project/documentation.git/blob/refs/heads/8.x-1.x:...
https://drupal.org/project/issues/search/documentation

@tim.plunkett, thanks!

Attached is first-stab at a patch to add details to the FAPI reference page. Two things (at least) that need work:

Is there an automated way to add the styling spans around code examples?
I can't figure out how to link to the D8 API docs. That may be a more systemic issue as all the other links point to the D7.

Setting to NR for the testbot.

Hm.

@@ -1945,7 +2029,7 @@ Format a group of form items.</p>
 
 <p><strong>Properties</strong>: <a href="#access">#access</a>, <a href="#after_build">#after_build</a>, <a href="#attributes">#attributes</a>,
 <a href="#collapsed"><strong>#collapsed</strong></a> (default: FALSE), <a href="#collapsible"><strong>#collapsible</strong></a> (default:
-FALSE), <a href="#description">#description</a>, <a href="#element_validate">#element_validate</a>, <a href="#parents">#parents</a>,
+FALSE), <a href="#description">#description</a>, <a href="#group">#group</a>, <a href="#element_validate">#element_validate</a>, <a href="#parents">#parents</a>,

This change seems to be unrelated?

 <p><strong>Description</strong>:
-Format all child fieldsets and all non-child fieldsets whose <a href="#group">#group</a> is assigned the element's name as vertical
- tabs.</p>
+Format all child fieldsets and details and all non-child fieldsets and details whose <a href="#group">#group</a> is assigned the element's name as vertical tabs.</p>

This sentence has too many "and"s in it.

The rest looks OK. And no there is no good way to edit this document, format code, etc. That is why I have been lobbying for years to get rid of it and do this in another way, but so far... hasn't happened. :(

This change seems to be unrelated?

Kinda sorta... I was trying to correct the fieldset docs (by adding the #group attribute) so that they matched the new details docs. Ideally, I would've done it as a separate issue but this file is a beast to edit! I suppose I can pull it out, let me know your preference.

This sentence has too many "and"s in it.

Boy does it... I'm curious why the original text specified "all child fieldsets and all non-child fieldsets." Doesn't that mean just "all fieldsets?"

How about this instead: "Format all fieldsets and details details whose #group is assigned the element's name as vertical tabs."

The attached patch makes this change.

And no there is no good way to edit this document, format code, etc. That is why I have been lobbying for years to get rid of it and do this in another way, but so far... hasn't happened. :(

*groan*

Would you be open to patches that clean up some of the inline styling and add some better/more consistent indentation, etc.?

Regarding the lobbying effort:
#100680: [meta] Make API module generate Form API documentation (API module issue)
#1617948: [policy for now] New standard for documenting form/render elements and properties (Drupal Core coding standards issue)

And definitely, I'm open to patches that clean up styling. If you file a new issue and upload a patch, assign it to me so I see it. I don't watch the Documentation project issue queue much, so sometimes the patches on API docs files like FAPI reference languish too long. Sorry. :(

And regarding this patch...

I just figured out what this sentence was trying to say:

 <p><strong>Description</strong>:
-Format all child fieldsets and all non-child fieldsets whose <a href="#group">#group</a> is assigned the element's name as vertical
- tabs.</p>
+Format all fieldsets and details whose <a href="#group">#group</a> is assigned the element's name as vertical tabs.</p>

What it previously meant was that it adds the following as vertical tabs:
- All child fieldsets
- All non-child fieldsets (other fieldsets in the same form) whose #group property is set to whatever this element's name is

So it is not really "all fieldsets". Can you figure out a wording that captures this, or make a UL list of that would be clearer?

Other that that, I think the patch is fine.

After enough rewrites to make this the Great American Novel, how does this sound:

"Formats all child fieldsets or details as vertical tabs. Non-child fieldsets or details can be added to the vertical tab by setting their #group to the vertical tab's element name."

(edit: interdiff is against #5)

The text suggested in comment #12 is great. The patch didn't quite get it right though.

Ah jeez... Sorry about that.

Grammatically correct version attached. Interdiff is against #12.

Thanks!

#2177469: Move node base widgets to the top level of the form is proposing the addition of a new #optional element to details to make them hidden when no children exist. That would need to be documented here or in a followup if not on this one (opened #2199321: Document #optional on details for that).

Sorry for the delay. Finally committed this to the 8.x-1.x branch of the docs repo. Please do any further changes in a different issue.