Since the mailing list is currently down, I'll cut and paste my email here:
I was looking through the wiki page The Loop, based on feedback from the forums.
I think that it stops short of providing enough truly useful information. It
reads like it's describing a space ship, but it doesn't actually tell you how to
use it. I would say that improving this page should be a Codex priority right now.
I'm all for multiple examples, but are these two the best ones? The second one is surely useful, but the first is fairly similar. Is there something else that would be more useful? --MDAWaffe 02:10, 10 Feb 2005 (GMT)
Lorelle 03:18, 10 Feb 2005 (GMT)
Some editing questions:
1) $post variable - can we have a link or better definition of this since it kind of pops into the paragraph and is a bit intimidating. A link would be enough for those of us learning by dragging our brains behind us.
2) In the first paragraph, the simple child in me who needs to be talked to with baby talk, wishes it said something like this (but in a more adult voice):
The phrase "process each of the posts" is way too simple a concept for what The Loop really does and for us simple folks, we need a little more explanation. What does it process...vaguely?
3) Under "The Loop" in 1.5, it states that the loop should be placed in the index and other templates. Version 1.5 actually hosts 2 index.php files. Should be be specific that it refers to the index.php in the themes?
4) Examples: I think it would be better to clearly label the title as " Style Posts from some Category Differently - v1.5 only" so there is clarity for the version issues.
I thought of a very simple example to show. How about one that puts the excerpt into the loop? Along with the css. Very simplistic, and very common. It would help people simply understand the process of the Loop.
Great work!
Lorelle 03:50, 10 Feb 2005 (GMT)
I'll say more in a moment. I just wanted to let you know I'm doing a quick revert on your last edit. I'll explain in detail momentarily. --MDAWaffe 04:00, 10 Feb 2005 (GMT)
OK, lots of good points.
1) $post variable - You can do, I think, anything without this variable simply by using Template Tags and other WordPress functions; it should probably be removed from the introduction. My guess is that this is the kind of thing that will never be well documented; it's a very complicated object (and it's deprecated in 1.5). Any documentation will be aimed at "experts" and would be very terse. Even so, the doc would be a pain to write up (and as it's old news...).
2) How about this for the introduction:
When The Loop runs, it cycles through and collates each of the posts being requested, and generates the final HTML to be sent to the viewer as specified within The Loop. This final HTML is specified both by PHP code (such as Template Tags) and HTML code between where The Loop starts and where The Loop Ends. It is here within The Loop that the information about your Posts and Pages is drawn from your MySQL database.
Since, during this process, The Loop is able to format all of your Posts consistently, styling the final HTML it generates with CSS is made relatively simple.
===A Note About Template Tags=== When WordPress documentation states "This tag must be within The Loop", it is referring to the region between where The Loop starts and where The Loop stops. For example...
3) Yes, I'll change that. Excellent catch.
4) I would prefer a warning directly under the title. Titles with too much extra information get long (uglifying the table of contents) and hard to use as #anchors: [[The Loop#Style Posts from some Category Differently - v1.5 only]]
is_home()
:). Again, in the works.have_posts()
... to avoid the misquoting issue. I'll see what I can do.OK - so I tried putting in things like [The functions] and [The] $wp_query [object], and I couldn't figure out a way that left it at all readable but still preserved the actual e-mail. Remember, they're quotes not paraphrases. (They're quotes because I think Ryan and Alex explained things quite well). Open to suggestions. --MDAWaffe 05:03, 10 Feb 2005 (GMT)
Lorelle 01:00, 11 Feb 2005 (GMT)
We all agree that no one wants the time they spend on a task ending up wasted, so before further effort is taken to expand The Loop, please note that I was asked to do just that. I don't see a real problem here, but it's something we should be careful about in this freeform editing environment.
-Kaf 05:31, 10 Feb 2005 (GMT)
To avoid further fistfights, and since I've been asked what I'm putting together for a rewrite of the page:
My main objectives are fourfold. 1. Add an introduction that explains The Loop, with a non-technical summary of its workings and what does what; 2. Flesh out The Loop code entries to better display its fit in a template and explain how to work with it and template tags; 3. Add a section on the comment loop; 4. Provide a list of all template tags specific to The Loop, with a reference for those considered basic to a blog post.
Yes, there's a distinct lack of discussion or examples on how to customize The Loop for *advanced purposes*. This is because I was thinking (serendipitiously?) of a need for a separate Customizing The Loop as an adjunct page. This could provide a sandbox of sorts where user solutions to a number of issues can be written up. The material already placed (and discussed) here would work extremely well in an initial version of such a document.
Normally I'd ask for opinions on that last idea, but I think it extremely important to separate basic "help me recognize this in a line-up" information on The Loop from anything that helps users gain greater control of it.
-Kaf 03:02, 11 Feb 2005 (GMT)
For the category exclusion example, the alternative method using Ryan's Front Page Categories should be mentioned.
Advantages:
Disadvantages:
Thoughts? --MDAWaffe 23:18, 12 Feb 2005 (GMT)
At the bottom of the Advanced section, just before the link to the author's name, is HTH. What does this mean and is it important? Can it go? Lorelle 21:09, 17 Feb 2005 (GMT)
Before we hit the road full-time in our trailer - gee, over ten years ago - the most helpful and brilliant thing we did was to get involved with the Compuserve RV Forum which told us MORE than we ever wanted to know about living in a trailer and living on the road. The most frequently used reference, created there (and I see it pop up once in a blue) is HFWPOH, later to be replaced by the famous Homer Simpson's "doh!" It means "Hit Forehead With Palm Of Hand". Do it and you will know EXACTLY what it means...I live it everyday...still...10 years later, still learning. Lorelle 21:42, 22 Feb 2005 (GMT)
I'm finding links to this page set as the_loop and others as The_Loop. Both seem to come to this page, but is there one preferred over the other? Lorelle 19:09, 4 Mar 2005 (UTC)
The_Loop is better, but mediawiki is not too concerned about capitalization anyways.
I just tried using another non-capitalization link that should have been and it linked to "create a new page". I changed the caps and it went to the right page. Frustrating. Lorelle 19:00, 5 Mar 2005 (UTC)
I see frequent mention of is_home(), is_archive(), etc. but I can't find a page that specifically describes these things and what they are and how to use them. Do we have anything written up yet? I assume they are part of the the Loop. Lorelle 00:15, 5 Mar 2005 (UTC)
So still in the works, yet? Well, folks, get with it! Thanks. Lorelle 18:59, 5 Mar 2005 (UTC)
skippy 00:30, 26 Jun 2005 (UTC): I have replaced the // Do stuff comment in all the examples with <!-- Do stuff... -->. The two forward slashes are PHP comments, but they were consistently used outside of PHP tags, which would lead to breakage if they had been copied-and-pasted.
This looks like a minor edit to me, but I'm new at this, and I could be reading the PHP wrong. Better safe than sorry. In the "multiple loops in action" section, I changed the following word in bold:
I changed it to featured because unless I'm reading the code wrong, the category in the code is "featured", not "frontpage".
<?php $my_query = new WP_Query('category_name=featured&showposts=1');
Kirabug 02:02, 18 Oct 2005 (GMT)
User:Lorelle/Codex_Categories#Customizing_WordPress User:Lorelle/Codex_Categories states that this article is in the "Customizing WordPress" category, but I see that not in the footer. --bentrem 06:56, 13 Dec 2007 (UTC)
The description for 2.5 was rather, *ahem* bland, so I merged it with 1.5 and changed the title to "Wordpress 1.5-2.7" --Lightdifference 23:28, 11 December 2008 (UTC)
I'm going to add an example for nested loops in the multiple loops section:
$my_query = new WP_Query( "cat=3" ); if ( $my_query->have_posts() ) { while ( $my_query->have_posts() ) { $my_query->the_post(); the_content(); } } $GLOBALS['post'] = $GLOBALS['wp_query']->post;
Restoring $post is necessary because $post->comment_status of the parent post can be wrong after running the inner loop (I'm running that code from a shortcode). Any comments are appreciated, I'm not sure this is bug-free.
Nkuttler 11:25, 18 January 2010 (UTC)
I have tried the multiple loop codes in this page in WP 2.9.2 (http://azimuth-qsm.com/). It works but it displays the whole article, not only the teaser (the text before tag in post content), as the_content('Read more »');
should do. The same code works in WordPress 2.8.6 (http://ecmeurope.net/).
Since http://codex.wordpress.org/Function_Reference/the_post redirects ehre, it sure would be nice if the complete documentation for the_post() was here. Or at least, if what documentation there is were easier to find, rather than buried a few screens down, tucked into two text paragraphs after a handful of examples of using the function fly by with no explanation of what it does. That's not how technical documentation works.
Look, I get that this page is written for a non-technical audience, and that this is wordpress' entire M.O. But it would be nice if the part of the documentation that claims to be for technical people were actually written for technical people. The URL http://codex.wordpress.org/Function_Reference/the_post *ought* to just be the freaking technical documentation with a link out to this page. Vynce 21:21, 21 April 2011 (UTC)