The current API doc for element_children() (http://api.drupal.org/api/drupal/includes--common.inc/function/element_c...) only says this:

Return the children of an element, optionally sorted by weight.

In fact, it is not explained anywhere right now what a "child" is. This related issue is about adding this information to the documentation of drupal_render(): #1253828: drupal_render doc should explain what "child" means.

I wonder if it would not be a good idea to add a similar explanation to the doc of element_children(), in order to increase the chance that a developer wondering "How do I extract all elements that are not #-properties from an array?" finding the doc of this function. Right now, the documentation is really only useful to someone who already knows what a "child" is.

Support from Acquia helps fund testing for Drupal Acquia logo

Comments

jhodgdon’s picture

Issue tags: +Needs backport to D7

Sounds like a good idea!

sven.lauer’s picture

Okay, I'll see if I can find the time to do a patch. Probably after #1253828: drupal_render doc should explain what "child" means is in/decided, so that we can link there for details.

sven.lauer’s picture

Attaching two patches. The 'minimal' one contains a minimal change with a reference to drupal_render(). Th 'extensive' one tries to explain why the distinction of '#'-properties and 'children' is useful in the first place.

One might ague that this information should go into the doc of drupal_render(), but I kind of like the current doc there. Also, the notion of #-properties vs. children is useful more generally, and element_children() seems a good place to say why.

jhodgdon’s picture

Status: Active » Needs review

Presumably you wanted these to be reviewed - which one are you advocating?

sven.lauer’s picture

Ups, yes, forgot to set the status.

I am in favor of the more extensive one.

jhodgdon’s picture

Status: Needs review » Needs work

Hm. Actually, I like the idea of only maintaining the "what is a child" docs in one place, so I think the minimal approach is better? The extensive one seems a bit repetitive to me anyway.

Other things to fix in this patch:
- Verb tense in the first line of this doc block "Return the children of an element, optionally sorted by weight." --> returns
- @param "$elements The element to be sorted." seems ... The parameter name should be $element not $elements I think, and it should say "the element whose children are to be listed" or something like that?
- I also think "The children of a given array " should be "The children of an element" (use consistent terminology)?

sven.lauer’s picture

Okay ... my thinking was that the drupal_render()-doc does not quite explain the general rationale of making use of #-properties and children (in the sense that it is a way to represent a tree structure together with node-specific properties in a single structured array). And also that this kind of explanation maybe should not be in drupal_render(), because the concept is more general (even though renderable arrays may be the only place the concept is used right now). Re-reading the extensive patch, I agree that it is somewhat redundant, though.

Also, I would not have rolled two patches if I had not been in two minds about this ... so I guess I agree with your reasoning.

Rerolling,
- taking into account the person feature of the initial verb.
- I kind of was bothered by "return(s) the children ..." because the function will not return the children (arrays), but rather their keys in the parent array. Changed this to "Identifies the children ...", which seems more correct wrt what the function does.
- Wrt to the @param: Ugh, completely failed to see this.
- Wrt to the parameters' name: $elements is what the parameter is named in the function signature ... should something like this be changed in a doc patch?
- Finally, we have the element/element ambiguity--- "element" as a drupal term vs. "element" as "a thing in an array". Making the change suggested would have ended up as "The children of an element are those elements that have a key that does not start with a '#'"---so I replaced the suggested "element" with "element array" and went with "key/value pair" for the other occurrence.

sven.lauer’s picture

Status: Needs work » Needs review
FileSize
710 bytes

Aaaand actually attaching the patch.

jhodgdon’s picture

Status: Needs review » Reviewed & tested by the community

This looks good to me. Minimal but sufficient. :)

webchick’s picture

Status: Reviewed & tested by the community » Fixed

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

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