API page: http://api.drupal.org/api/drupal/includes--common.inc/function/drupal_re...

The documentation for drupal_render() is quite detailed, but it speaks of elements "having children" without saying what that means. I don't think this is actually made clear anywhere (at least not in the doc element_children() or drupal_render_children()). Even if it is, the documentation for drupal_render() should point there.

(A "child" of a Form or Render array is simply an entry whose key does not start with '#'---and hence whose value is not the value of a Form/Render API property, but rather holds a "sub-element" that (typically?) is a Form/Render array in itself.)

#10 1253828-doc-drupal_render-children-10.patch1.98 KBsven.lauer
PASSED: [[SimpleTest]]: [MySQL] 33,305 pass(es). View
#5 1253828-doc-drupal_render-children-5.patch712 bytessven.lauer
PASSED: [[SimpleTest]]: [MySQL] 32,875 pass(es). View
#2 1253828-doc-drupal_render-children-2.patch705 bytessven.lauer
PASSED: [[SimpleTest]]: [MySQL] 33,660 pass(es). View


jhodgdon’s picture

Title: Documentation problem with drupal_render » drupal_render doc should explain what child means

Sounds like a good addition to the doc -- just needs a patch...

sven.lauer’s picture

Status: Active » Needs review
705 bytes
PASSED: [[SimpleTest]]: [MySQL] 33,660 pass(es). View

Here is a first patch.

Possible issue: The added paragraph starts with "Renderable arrays ...", though the notion of a child element may be used more general.

Also (if I recall correctly), the things in arrays are by convention called "elements" (as opposed to "entries" or somesuch), so this patch conforms to this usage. This MAY create confusion, though, as the word "element" has a special meaning wrt the render API.

Looking at the doc again, I see some other small things that could make the documentation of this function clearer, should I open follow-up issues or discuss those here? (Most of them are slight changes in wording, e.g. "If it is set and the element has any children, they have to be rendered there. " -> "If it is set and the element has any children, it is the responsibility of the theme function to render the children. ").

sven.lauer’s picture

I just opened #1258176: API doc for element_children() is only useful for people who already know what "children" are to discuss if a similar addition should be made to the doc of element_children().

jn2’s picture

Regarding your statement, "This MAY create confusion, though, as the word "element" has a special meaning wrt the render API", I think it undoubtedly WILL cause confusion. This word's special meaning has been around a long time in the Form API, in addition to the Render API. But there are alternatives.

Looking to php.net, (http://www.php.net/manual/en/language.types.array.php) how about 'key/value pair'? Very clear and specific.

So edited:
"Renderable arrays have two kinds of key/value pairs: properties and children."

sven.lauer’s picture

Title: drupal_render doc should explain what child means » drupal_render doc should explain what "child" means
712 bytes
PASSED: [[SimpleTest]]: [MySQL] 32,875 pass(es). View

I agree that "key/value pairs" is a good choice in this instance, given the rest of the paragraph and also given the fact that it is not just about the values in this case. So I re-rolled.

BTW, to my knowledge, there is no place where "element" is defined/explained in the doc ...

jhodgdon’s picture

Status: Needs review » Needs work

I like this... but it doesn't quite explain why a renderable array would have children or how they would be rendered relative to the parent?

sven.lauer’s picture

The "how they would be rendered relative to the parent" is actually explained in the rest of the doc of drupal_render() (but it could be much clearer). I've been meaning to think about a larger rewrite of this, in particular including all the #-properties that are used by drupal_render() (and hence are available to ALL renderable arrays, form api or not). The latter I had started in my in-progress patch for #1230700: Documentation for hook_element_info() is very outdated, talks only about Form API, does not document #theme, #theme_wrappers ---but it really belongs neither there nor here.

I think the best place to explain such fundamental conceptual things as "What are children?", "What are children good for?", "What are 'elements'?" etc. and possibly a list of these most general #-properties would be a render API @group. There is a handbook page that tries to showcase the render API http://drupal.org/node/930760, which is useful for some purposes, but does not do a particularly good job explaining the basic concepts needed to understand the api doc of render-related functions. A @group would be a good central place to introduce these, and it could be automatically linked via @ingroup directives (or @see, where appropriate).

#100680: [meta] Make API module generate Form API documentation will surely become relevant to this, but again there is the question what can be done in the meantime. Also, regardless of how that issue pans out, there will be a need for a place to explain basic terminology, and a @group seems like a good idea for this.

Time permitting, I would be willing to work on a patch for such group (in particular, its "introduction"). This probably should happen in a separate issue.

Maybe in the meantime, we could just commit this patch as is? As I said, in the discussion of the #theme and #theme_wrappers property, the current doc for drupal_render() does explain how children end up being rendered. The question "Why an array would have children?" is not answered, but maybe this is not really the place to do that ...

Alternatively, one thing we could do is give an example of a type that has children ... don't know which one would be the best case to use, but that should make clear what the general idea is.

jhodgdon’s picture

Hm. The thing is, this is close to the top of the doc, and it left me with questions that were not answered until much later (if at all). So maybe either move this down or ... ?? Not sure, but I'm not excited about it as it is.

As to the larger question, let's not do that yet. There's been a lot of discussion on that form API reference issue lately and something may be done soon... or not, but at least we could do the core doc part until someone tackles the API module part.

sven.lauer’s picture

Okay. Let me see if I can do a more extensive rewrite of the drupal_render() doc so as to (a) avoid duplication and (b) make clearer how the rendering happens.

sven.lauer’s picture

Status: Needs work » Needs review
1.98 KB
PASSED: [[SimpleTest]]: [MySQL] 33,305 pass(es). View

Getting back to my open doc patches.

Here is another iteration, which actually keeps the changes local, but does provide more info about children early on.

The patch also includes a slight rewording in the description of the "#theme" property ("If [...] the element has any children, they have to be rendered there." => "If [...] the element has any children, it is the responsibility of the them function to render these children.")

jhodgdon’s picture

Status: Needs review » Reviewed & tested by the community

Wow. I think this is really clear and it reads really well to me, and it explains the issue reported (that "child" was not clear). Let's commit it! (d7/8)

webchick’s picture

Status: Reviewed & tested by the community » Fixed

Holy cow!! GREAT work!!

Committed and pushed to 8.x and 7.x. Thanks!

Automatically closed -- issue fixed for 2 weeks with no activity.