Document common form/render element properties

This looks really good! I learned a lot just from reading it ;)

It took me a moment to get used to the conventions what "read only" actually meant. Not sure if we should tackle that in the render api page.

+++ b/core/lib/Drupal/Core/Render/Element/RenderElement.php
@@ -17,6 +17,50 @@
+ * - #attached: (array) Array of attachments associated with the element. Can
+ *   include elements:
+ *   - library: (string[]) Names of CSS/JavaScript libraries to attach.
+ *   - drupalSettings: (array) Drupal JavaScript settings to attach.

This really needs a see reference, but I'm not sure where to. A newbie is likely to just start trying to list css/js files in this list. Have any ideas? Loading css/jss is a primary task for a module developer. I'm kind of surprised we don't have a "Rendering" or "Libraries" section in our core topics list, but perhaps a link to https://www.drupal.org/developing/api/8/assets would be appropriate here?

+++ b/core/lib/Drupal/Core/Render/Element/RenderElement.php
@@ -17,6 +17,50 @@
+ * - #id: (string, normally read-only) The HTML ID on the element.

What does (normally) mean here? How would I know whether to set this value or not?

That fixes it from my perspective. I'm going to try and test the #id attribute on render elements... I think that's a better pattern for ajax container examples, and should probably update the sample code accordingly.

This looks great, thanks!

+++ b/core/lib/Drupal/Core/Render/Element/RenderElement.php
@@ -17,6 +17,67 @@
  * Provides a base class for render element plugins.
...
+ * Render elements have properties. Some are specific to a particular type

so this is a super tricky because what are render elements? In Drupal 8 they are really still arrays! So they don't really have properties and it is a bit confusing to say they do in the context of saying this on the base class for render element plugins - which would intimate that render elements are objects which have properties.

I think we are missing #markup, #plain_text and #allowed_tags. Every element will at least have #markup set by rendering and some elements are designed have it set first.

What also might be able to be moved here is the security documentation for #suffix and #prefix.

I also think we need to mention security here since we're saying that many of the properties are displayed to users.

Also I'm pondering where #field_prefix and #field_suffix should go too.

added #markup, #plain_text and #allowed_tags.

modified patch #10 and resubmitted for review.

This is looking good. Thanks Jennifer. I've got a few comments that I think will help to make this a little easier to read, and a few mistakes that should get cleared up before this get committed.

1. +++ b/core/lib/Drupal/Core/Render/Element/FormElement.php
   @@ -15,18 +15,24 @@
   + * arrays and render elements, and the @link form_api Form API topic @endlink
   

   It looks like the link to https://api.drupal.org/api/drupal/core%21lib%21Drupal%21Core%21Render%21... was removed, and I think it should still be here. Specifically, "arrays and render elements" should be a link.

2. +++ b/core/lib/Drupal/Core/Render/Element/FormElement.php
   @@ -15,18 +15,24 @@
   + * form processing of most/all form elements:
   

   Is it most, or is it all? It seems weird that this is kind of ambiguous. Or is that ambiguity intentional?

3. +++ b/core/lib/Drupal/Core/Render/Element/FormElement.php
   @@ -35,15 +41,18 @@
   - *   sparingly; make sure it is translated.
   + *   sparingly; make sure it is translated. If it is not already wrapped in
   

   I find the use of the word sparingly a little weird here. Probably because I don't fully understand why we're telling someone to use this property sparingly? Is it because we want you to keep it short and concise, or because there is another better way to provide inline help to users of a form?

4. +++ b/core/lib/Drupal/Core/Render/Element/RenderElement.php
   @@ -17,43 +17,77 @@
   + * that although in the properies list they that follows, they are designated
   

   "list they that follows" should be just be "list that follows" I think.

5. +++ b/core/lib/Drupal/Core/Render/Element/RenderElement.php
   @@ -17,43 +17,77 @@
   + * - #allowed_tags: (array) Array of allowed HTML tags for XSS filtering of
   + *   #markup, #prefix, #suffix, etc.
   

   I wonder if it makes sense to @see \Drupal\Core\Render\Renderer::ensureMarkupIsSafe here?

6. +++ b/core/lib/Drupal/Core/Render/Element/RenderElement.php
   @@ -17,43 +17,77 @@
   + *   theming for the element. This will be filtered during rendering; see also
   + *   #plain_text and #allow_tags.
   

   I think this should be #allowed_tags, not #allow_tags

7. +++ b/core/lib/Drupal/Core/Render/Element/RenderElement.php
   @@ -17,43 +17,77 @@
   + * - #plain_text: (string) A plain text override to #markup. HTML tags will
   + *   be escaped in this text.
   

   I was having a little bit of trouble trying to figure out when I should use #markup and when I should use #plain_text, the documentation for \Drupal\Core\Render\Renderer::ensureMarkupIsSafe helped to clear this up a little bit for me but I think we could be a bit clearer about it here. That documentation says, "Render arrays can escape text instead of XSS filtering by setting the #plain_text property instead of #markup." if that's helpful at all.

8. +++ b/core/lib/Drupal/Core/Render/Element/RenderElement.php
   @@ -61,11 +95,17 @@
   + * - #render_children: (bool, internal) Set to FALSE by the rendering process
   + *   #theme should be bypassed (it's normally used to render the children).
   

   I think this sentence is missing an "if" somewhere. It doesn't read smoothly without it.

The cleanup looks good to me. The sections on #plain_text especially are much easier to follow now. I think we can go ahead and this added. Thanks!

Committed d648b71 and pushed to 8.0.x. Thanks!

One thing we didn't have documented was placeholders. I decided this deserved a new section of the Render API topic, because it was too complicated to describe in a few words.

I don't see where #placeholder is documented on RenderElement, FormElement, or any of their subclasses. Yet it is used throughout core. (This is also true of dozens of other tags, BTW.) #2226275: Update Drupal 8 Form API reference was closed as a duplicate of this issue, so it was expected to be fixed here. We have gone from an outdated and hard to maintain "Form API reference" document to no documentation at all for many of the properties.

The Render API overview at https://api.drupal.org/api/drupal/core!lib!Drupal!Core!Render!theme.api.... mentions placeholders only in the context of build arrays, not form elements, and mentions that you can use '#attached' => ['placeholders' => ['@foo' => 'replacement']], in a build array, but I don't see that feature used in core and it's not clear whether this is the new way to do things (and core hasn't been updated yet) or its the old way to do things (and the documentation hasn't been update yet) or whether it's one of those dead-ends from the D8 development process that's no longer true. Regardless, #placeholder *does* work, and is used in core, but is not documented.

Well it's been less than four months, not really a long time as far as core issues go. All the context is in this thread, and other threads which have raised this issue have been closed as duplicate of this thread. So I still think it's reasonable to deal with the problem in the same place where it was worked on and should have been resolved.

But if you want, I'll open some new issues for the things that were missed here.

EDIT:

I'm working on this ...
Would you like one issue for everything, say "Document common form/render element properties, Part II" or would you like one issue for each undocumented property, or one issue for each of the elements that are missing property documentation? I'm already up to 30 undocumented properties, and I'm only part way through the list of form and render elements ...