Codex

Interested in functions, hooks, classes, or methods? Check out the new WordPress Code Reference!

Talk:The Loop

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.

NuclearMoose 06:51, 12 Jan 2005 (GMT)
I'll second that. The "Multiple loops" section makes zero sense.
19:23, 27 February 2009 (UTC)

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)

Excellent examples.


I noticed that the tag names and their links are styled different from the rest of the codex. I like featuring the name, but I'm bothered by the way the tag looks inside parenths. Kinda confusing. Right now, I'm too tired to make a decision, but I wanted to point it out so we have consistency and clarity. I guess I think they should just be the tag name like the_content() as it is as a link because that is what it is in the Loop, and then we use words to explain them, like "The Title is named the_title() and..." or "...within the post content, called the_content()..."

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):

"When The Loop begins to work, it gets the bits and pieces of information requested from the database and then moves through the various html, php, and css codes to sort and order the information, and when it is done, it displays on the page all pretty."

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.

a. This is the first time permalinks are mentioned on this page and there should be a link from the word...I think.
b. In the note under Exclude Categories, there is a reference to creating a different template because the exclusion would apply to the categories...is this a Page reference? If so, we need to be specific and link to the "how to make a page" page.
c. In same note, there is a reference to home_is(). Gotta have a link to this to help us know what it is.
d. Because the Advanced section specifically references information from "Ryan", it is more personal that the rest of the page. I'm nervous about editing such sections, though I think if this stays on this page, it would be better to make this a serious addition to the page and include a reference credit at the bottom of the section to him (or her) so the page has a professionally clean and uniform look.
e. In general, it ain't kosher to start a sentence with a numbered number, like "14 is the number you want." It should be "Fourteen is the number..." Starting sentences with a lowercase tag name is outside of the scope of this humble editor, but it looks strange. Is there a way to put a The or move the sentence around a little so it starts with a captial letter? I bring this up because in the Advanced section, "PATH_INFO. $wp_query" are in code format and at the end of one sentence and the beginning of the other. It is a little misleading as to where one starts and one ends. There isn't a way to captialize a dollar sign, but it would help if it was a little more clear and separate.

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...).

This was unfair of me as their's an analogue in 1.5. It was kind of a cop out on my part. It probably should, though, be removed from the introduction or moved to a specific part of the introduction which clearly labels itself as advanced information. Anyway, you're right. It'd be nice to eventually have some documenation on it. Other things are probably higher up on the list though --MDAWaffe 10:31, 10 Feb 2005 (GMT)

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]]

a) OK
b) No, this is not a Page reference. More extensive Template Docs are in the works and will be linked to when ready.
c) is_home() :). Again, in the works.
d) The reference made above the the first e-mail (directly under the section title). It's a him - the famous Ryan Boren, WordPress developer extraordinaire. We can link to his site from the FROM: bit as well as his final sig if you think it's appropriate.
e) I reverted your edit to this section for two reasons.
  1. I understand the need for clarity, but I wanted to make these sections direct quotes from the e-mail. I believe the people who know enough about PHP and the innerworkings of WordPress to use this information will find it readable. I truly hope this does not sound offensive or elitist, but this is the Advanced section (with a friendly warning up top). It gets more technical, and the reader should expect some jargon. But if you'd prefer, we should do it something like [The functions] have_posts()... to avoid the misquoting issue. I'll see what I can do.
  2. They aren't tags, in my opinion. Kaf, Carthik and I have been discussing the issue, and I've been made to see the light. But here I'm still stubborn. I don't think we shoukld try to stretch the "tag" nomenclature too far. Others please chime in to debate.

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)


EXCELLENT. The new intro sounds perfect. When I look at all I mentioned, it's a wonder because I was shattered tired last night but I felt these things were important. I'll look at the tags/codes at beginning of sentences again later and see what might work but everything looks slicko great. Glad I could help a little with my nags.
LATER: Within this codex, when is a quote a quote and when is a source a source? In other words, just because information is contributed from one person, and that person gets the credit, is it free from editing? I'm not talking major edits, but grammar and such. Do you all have a policy on this? This codex is a wiki, right, so where do you draw the line?
Lorelle 16:56, 10 Feb 2005 (GMT)
Caught another one: Under Advanced, are these for v1.5 or 1.2 or both?
Also, there is a mention of Title, Categories, etc. in the intro describing the Loop and no reference in any easy example. Let's hold off questions on where these go in the loop by giving a simple example with them, and one using the excerpt, within the Loop.

Lorelle 01:00, 11 Feb 2005 (GMT)

Currently the Advanced section contains only 1.5 Loop. You can see that the syntax is the same as that described in Using The Loop. I don't quite know what you mean by the Title etc., both examples show Title, Category and Time as mentioned in the Intro. --MDAWaffe 04:27, 11 Feb 2005 (GMT)
As for the quoting issue - I was lazy. It was a pretty good (if brief) explanation, so I just grabbed it. I just wanted to preserve the quotes while they were quotes. It'll probably get retooled and revamped in the future. --MDAWaffe 05:59, 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)

I apologize, I was not aware. I hope you had not spent too much time on this, and if you have, I hope it can be easily merged with (supplementing/replacing) what is here now. I saw NuclearMoose's note up top and went at it. Perhaps a note in the Discussion regarding one's todo list would be appropriate. --MDAWaffe 06:42, 10 Feb 2005 (GMT)
I responded at your user talk page, but I think it's important to be clear for others who may happen upon this: by taking up the chore of rewriting the page, you were doing exactly what you should be doing. So there's no need to apologize, to me or anyone else. The only reason for my note above is that there's a lot left to do, and nobody--you, me, any of us--wants their time to be spent accidentally duplicating someone else's work.
In the future, I'll make it clear the documents I'm working on. A good rule, considering.
-Kaf 08:48, 10 Feb 2005 (GMT)

Expanding on The Loop

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)

I was just thinking something similar. Actually, I thought it might be useful to have a Examples/Sandbox page associated with any page talking about code. This would allow peopl to write down examples they'd thought useful without cluttering up the main documentation. Maybe for every template tag, the loop, is_, ... Pages, ... I'm sure there's others, a subpage could be made: The Loop/sandbox or The Loop/examples. I know Codex frowns on subpages in general, but this seems like a logical way to associate examples from users with a specific page without having to create new top level pages all the time. --MDAWaffe 04:27, 11 Feb 2005 (GMT)
Opinion-wise, I wouldn't have a problem with it as such, though I believe they should come about organically. By that I mean, say if a particular tag gathered up several complicated examples (or we saw a need for such), they could be moved off to an examples sub-page.
-Kaf 04:54, 11 Feb 2005 (GMT)
Fair enough. Good call. --MDAWaffe 05:33, 11 Feb 2005 (GMT)

Examples

For the category exclusion example, the alternative method using Ryan's Front Page Categories should be mentioned.

Advantages:

  • Don't pull posts from DB that aren't needed (uses posts_where and posts_join hooks)
  • Displays corrent number of posts per page

Disadvantages:

  • posts_where and posts_join seem like they can only be used by one plugin at a time if you want any kind of predictable results.

Thoughts? --MDAWaffe 23:18, 12 Feb 2005 (GMT)

Actually - nevermind. The plugin doesn't really work all that well for excluding categories. --MDAWaffe 12:34, 21 Feb 2005 (GMT)

HTH?

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)

"Hope That Helps". HTH --MDAWaffe 12:34, 21 Feb 2005 (GMT)
In the interest of fair play for all of us idiots out there overwelled with figuring all of this stuff out, I deleted the HTH so others don't ask the same questions I do. After all, HFWPOH, we all have to learn the hard way. Lorelle 21:12, 21 Feb 2005 (GMT)
Ok - you got me on that one. --MDAWaffe 05:56, 22 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)

The Loop or the loop?

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.

Carthik 19:25, 4 Mar 2005 (UTC)
That's news to me. I've made a few mistakes in caps on some links and got a page not found. Is this something that's been fixed recently? If it is true, that takes a lot of the stress out for me. I've had some ugly problems with this. Lorelle 00:10, 5 Mar 2005 (UTC)

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)

"is_" variables

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)

Templates, Conditional Tags
MDAWaffe 01:38, 5 Mar 2005 (UTC)

So still in the works, yet? Well, folks, get with it! Thanks. Lorelle 18:59, 5 Mar 2005 (UTC)

Ding - Thanks to Carthik (and yourself), the above articles are live. I've updated the links to them. --MDAWaffe 21:00, 6 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.

loops in action example typo?

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:

Set $my_query equal to the result of querying all posts where the category is named frontpage and by the way, get me one post only.

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)

Nested Loops

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)

Problem with multiple loops and teaser in WP 2.9

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/).

More misdirection

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)