I would like to query only pages with a certain page template with
WP_Query or a function that would return the post object, but I can't find any information about that on the official codex.
Try this... Assuming the template name is 'my_template.php',
$query = new WP_Query( array( 'post_type' => 'page', 'meta_key' => '_wp_page_template', 'meta_value' => 'my_template.php' ) ); //Down goes the loop...
Incorrect: as of wordpress 3 you need something akin to:
$args = array( 'post_type' => 'page', 'meta_query' => array( array( 'key' => '_wp_page_template', 'value' => 'my_template.php' ) ) );
The page template is stored as a meta value with key "_wp_page_template".
So all you need is to use that key in a meta query parameter. For examples
If anyone's attempt incorrectly results in zero posts, probably the template name is wrong. I tried the php file name and my template name and they didn't work. Then I decided to inspect the templates select box where we select the template on the page editor. I found this:
<option value="templates-map/component-tutorial-1.php" selected="selected">Tutorial -1</option>
templates-map/component-tutorial-1.php and it worked.
If you have the template inside another folder:
$args = array( 'post_type' => 'page', //it is a Page right? 'post_status' => 'publish', 'meta_query' => array( array( 'key' => '_wp_page_template', 'value' => 'page-templates/template-name.php', // folder + template name as stored in the dB ) ) );