show(), hide(), and render() documentation is misleading

er, what does 'for later rendering' do for us? i say remove it.

How about "mark a ... for later rendering"?

And as long as we're fixing this function doc, "which" should always have a comma before it:

* Alternatively, render($element) could be used which automatically shows the
* element while rendering it.

and is that part clear at all? What do these two functions actually do anyway???

OK, now you have me totally confused... I think this is all one documentation issue though.

Regarding #5 "Once render is called, show() and hide() have no affect on any subsequent calls to render()."... is this potentially because you didn't go high enough up in the render tree? (e.g. you said to show something, but it was already hidden higher up)? I guess I'm not understanding what is working, what isn't, and what you think should happen...

I did some more testing on http://drupal.org/node/929802#comment-3604502 and figured out what was going on, I think. Basically, show/hide only work before the first call to render(), because drupal_render() sets a #printed flag and never looks below the top level after the first call.

This needs to be documented on show() and hide(). Also, the render() documentation is wrong...

Here's a patch, which I think clarifies what happens in these functions.

I think #7 is a tremendous improvement ... I still had to read it read it twice before I fully understood, but I dont have any suggestions on how to make it better. Any other thoughts

print render($content) first, then hide($content['comments']) = hide() has no effect
print hide($content['comments']) first, then print render($content), and then show($content['comments']) = show() has no effect
Is it ??

so when to use show() ??
print show() first if render element set to #printed flag = TRUE by default ?

my test, I have removed all codes in node.tpl.php and paste @jhodgdon codes.

(I don't know what is the default behavior, so commented what I saw)

print "<br />content without adulturation<br />";
print render($content);
// (content + comment)


hide($content['comments']);
print "<br />content with comments hidden<br />";
print render($content);
// (content + comment)

show($content['comments']);
print "<br />content with comments shown<br />";
print render($content);
// (content + comment)

print "<br />comments only<br />";
print render($content['comments']);
// comment only

print "<br />content again<br />";
print render($content);
// (content + comment)

print "<br />now return to your regular programming<br />";

"Remove the first print render($content) line to test that if you hide initially"

hide($content['comments']);
print "<br />content with comments hidden<br />";
print render($content);
//only content 

show($content['comments']);
print "<br />content with comments shown<br />";
print render($content);
// only content

print "<br />comments only<br />";
print render($content['comments']);
// only comment

print "<br />content again<br />";
print render($content);
// only content

print "<br />now return to your regular programming<br />";

** D7-dev up to date

droplet: Please clarify - are you reviewing the patch in #7, and do you think it is correct/complete, or does it need work?

@jhodgdon,

Yes, reviewed the patch. I have read many time and don't really understand until testing examples code.
I'm not sure if I understand this 100% correctly, so draw a conclusion in my word above.

#7 is correct and complete if users understand what is elements/elements tree

"on an element low in the element tree"
=> xxx ..... lower in...xx
=>on an child element in the render element tree..

It's more clear to me.

** I'm not a native speaker

OK, that is good feedback, thank you! I think we should change high/low terminology in the patch to use more parent/child terminology, as I think that is more standard.

Here's a patch that hopefully changes the wording about show/hide to something that is clearer and only uses child/parent tree terminology.

This is much, much clearer. RTBC++ for me, but lets give it one more set of eyes...

Committed to CVS HEAD. Thanks.