Contrib.social

Render Array Documentation Initiative

Open on Drupal.org →
Created on 15 February 2021, almost 4 years ago
Updated 21 July 2024, 5 months ago

Problem/Motivation

New developers, learning how to code using Drupal "the Drupal way", often struggle to grasp the concept of render arrays. A large component of this is in my opinion, that render arrays often have their type documented, but there is no list of render array keys available. This leads to developers relying on posted questions and solutions on other platforms such as StackExchange, or guides solving a particular problem (if there is any guide at all), instead of consulting the documentation and trying to find the best way to solve the problem.

Steps to reproduce

Documentation of render array types (for example "File") can be found on their classes, if available. Examples:

Proposed resolution

All the possible render array keys (also the default ones like #title and #description) should be listed and described in the first part of the documentation.

On the File class, there are two out of seven possible render array keys listed and described. On the ManagedFile class, there are none documented. There should be at least every render array key listed in the description section (like on the File class) with a quick description on what can be achieved by defining this setting.

Additionally, a small section of code examples should also be included afterwards, so users see the logic and the syntax to define these setting.

The list of allowed keys could be based on public function getInfo() which is implemented on these classes.

Remaining tasks

  • List candidates for documentation changes (could be based on this list)
  • Add said descriptions to the documentation pages

User interface changes

None.

API changes

None.

Data model changes

None.

📌 Task
Status

Active

Version

11.0 🔥

Component
Documentation  →

Last updated 1 day ago

No maintainer
Created by

🇨🇭Switzerland florianmuellerch Aarau, Switzerland

Live updates comments and jobs are added and updated live.
Sign in to follow issues

Comments & Activities

Not all content is available!

It's likely this issue predates Contrib.social: some issue and comment data are missing.

  • Comment 5 months ago →
    🇳🇿New Zealand quietone

    What is the state of this initiative? It has been three years since this issue was opened and there has been no further discussion or action.

    And core are already issues throughout core to document various aspects of the render array and elements. Is this issue needed?

  • Status changed to Postponed: needs info 5 months ago
  • Comment 5 months ago →
    🇳🇿New Zealand quietone
  • Status changed to Active 5 months ago
  • Comment 5 months ago →
    🇨🇭Switzerland florianmuellerch Aarau, Switzerland

    @quietone Thanks for the engagement :-)

    I raised the issue out of the experience that all developers that I newly introduced into the Drupal ecosystem seem to struggle to grasp this concept, and still to this day, I didn't find neither a really comprehensive guide, nor an absolute overview over possible render array keys.

    This does not only need to be in documentation: Imagine a contrib module that goes through all modules and lists their render array keys. However I'm not sure if, as a contrib module, you would have access to list all the types and themes built into the core itself.

    There's just guidance and overview that is still lacking. If you have good resources (maybe also from elsewhere) please feel free to share!

  • Comment 5 months ago →
    🇳🇿New Zealand quietone

    @florianmuellerCH, I don't know of any 'good resources'. I rarely do anything with the render API.

    For this issue, I am trying to figure out what the plan is. What is the next step?

  • Comment 5 months ago →
    🇨🇭Switzerland florianmuellerch Aarau, Switzerland

    Someone with a bit of time on their hands should create a guide on drupal.org (I don't even know how that would work) and start a comprehensive documentation about how render arrays are working and how they're supposed to be used. Therefore I suggest to leave it open until we find that "someone".

contrib.social Blog FAQ Discussions
Production build 0.71.5 2024