Come together with the global Drupal community in Rotterdam, 28 Sept – 1 Oct 2026. Sessions, contribution, connection, and Early Bird savings until 8 June.Problem Statement
When Reading Render API documentation it is clear that a render array must be built, but it is unclear what render elements may be used in the render array or are provided by core.
Proposed Resolution
Add short statement to the Render API topic in the documenation provideding a see reference or link to the list of form elements provided at:
| Comment | File | Size | Author |
|---|---|---|---|
| #8 | 2680307-6-api-navigation.patch | 1.63 KB | metzlerd |
Comments
Comment #2
jhodgdonI'm not sure how exactly I'd suggest making this link... Ideally, as Drupal evolves into new versions, the link would take you to the appropriate elements list for the version of the page you are looking at... that is not easy to do, since we can only put in a URL that goes to one particular version.
So probably, rather than making a real URL link, we should instead tell them how to find the list on api.drupal.org, something like
Find the Elements list in the sidebar block ...
Comment #3
metzlerd commentedHmmm... I had actually not even seen the elements link in the sidebar. That does help the navigation. Do you think in the context of the documentation it would be better to rename that Render Elements, since that is how they appear to be referenced everywhere in the render api docs?
It's unfortunate that we can't provide a direct link. Is there no API page that we can reference, or any way to create api pages that reference these links? Or a way to display the list in an api page that we can reference in the docs? (Just trying to think outside the box).
Comment #4
jhodgdonSorry, there isn't a good way to do this.
You might look at what we did on the Services topic page:
https://api.drupal.org/api/drupal/core!core.api.php/group/container/8
I suggest we do something similar here... something like this:
API reference sites (such as https://api.drupal.org) generate lists of all existing form and render elements from these classes, or you can look for them manually.
Comment #5
metzlerd commentedDid you have an opinion about renaming Elements to Render Elements in the side bar itself? It would be nice if the language in the Render API at least was consistent with the API site. If so where would such a request get properly made?
Comment #6
metzlerd commentedSo i've been thinking more about this. The Render API documentation basically says you can search for them already (but doesn't tell you how). Most people who will be reading these docs will already be on an API reference site such as api.drupal.org. My real problem was that when I was drilled into and reading the API documentation. I didn't think to look in the API Navigation block, partly because I never would have thought that the API Navigation block would provide access to content that I couldn't get to any other way.
I don't think the language from services example does anything to solve my original issue, which is that I was thinking for some reason that there would be links to that embedded in the api docs. Now that I know about that block I probably will never look at the render API docs again for this information, but I'm left with an uncomfortable feeling that this will be something that you "Just have to know" about api.drupal.org in order to use it.
My own preference would be to go ahead and embed the specific links, even though they will need to get modified for every branch (because I think it's worth the maintenance headache), or to create an issue in the API project that would allow us to create these references in a sane way. So if we don't want to go down either of these two paths, my inclination is to just mark this as "won't fix", and move on.
It's a bit disappointing, but I'll get over it... ;)
Comment #7
jhodgdonRE #5 ... The sidebar is pretty narrow so I don't think I'll look favorably on renaming Elements to Render Elements in the sidebar. By the same token, the "Classes" link actually goes to "Classes, interfaces, and traits", but there isn't really room to put all of that there. If you want to request it, though, it would be an API module issue. project/api that is.
RE #6 ... I disagree strongly about embedding the specific links. That type of maintenance will never ever ever get done, and people will click on the links and not realize they're now in a different version of Drupal by mistake.
Let's instead figure out some language that would say to look for the links in the API site navigation block or something like that that would be clearer, and put it into both the Services and Render API blocks?
Comment #8
metzlerd commentedHere's a first stab. Thoughts?
Comment #9
jhodgdonI think this is perfect. Thanks!
Moving this to 8.2.x so the patch will be tested there. Needs to be committed to all 3 branches. Patch most likely will apply to all.
Comment #10
metzlerd commentedI verified that this patch is no different when generated against the 8.2.x branch and attempted to requeue the patch for testing. Not sure if I did that right... But I'm quite sure this will apply cleanly to 8.2.x-dev.
Comment #14
alexpottCommitted 839e34a and pushed to 8.0.x, 8.1.x and 8.2.x. Thanks!