Add function get_pages_by_template()

[mikeschinkel]

This patch adds a function get_pages_by_template() to /wp-includes/post.php. It accepts a page template string and returns an array of post objects keyed by the pages that use the template:

$pages = get_pages_by_template( 'page-about.php' );

Using WordPress for CMS I've been finding a need to provide links to specific pages in a more robust way than hardcoding their post_id or even referencing their post_name/URL slug and the way I've identified that works well is to locate a page by it's page template. Here a function that a theme might write that would use the function I'm proposing be added:

function get_about_page_link() {
  $pages = get_pages_by_template( 'page-about.php' );
  if ( count( $pages ) )
    return get_page_link( get_post( $pages[0] )->ID);
  return false;
}  

Unfortunately WordPress does not have efficient functionality in core that would allow a themer to lookup a page or a list of pages by their templates thus requiring the theme developer to resort to SQL which is ideally avoided.

Thus I'm providing this patch to enable a themer to do this lookup without having to resort to SQL.
The patch also fixes a typo that affects phpdoc in the same file: @parem => @param.

Adds get_pages_by_template() and fixes a phpdoc comment typo

Just as soon as I post this I realized that there is a way to get this without SQL. I'll upload another patch which will limit the justification for why this should be added, taking it from a must-have to a nice-to-have.

Updated get_pages_by_template()

I've just uploaded another version that uses WP_Query instead. It looses the ability to lookup with a SQL LIKE and to return the values keyed by post ID but it also uses built-in functionality and is probably faster.

I guess it would make more sense to set the default orderby value to menu_order as this will IMHO be used for menus mostly(?) and therefore should order by the default setting. Ordering by date sounds like an archive job.

menu_order doesn't have an index.

Replying to nacin:

menu_order doesn't have an index.

I know. But post_date doesn't make sense for pages. Further: You (hopefully) won't have thousands of pages.