Codex

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

es:Etiquetas de plantilla/get posts

Está página está en la lista de páginas incompletas. Tú puedes ayudar a Codex mejorándola.
Nota: no eliminar los enlaces originales en inglés hasta que existan en castellano Diego AG 11:28, 26 December 2013 (UTC)

Descripción

El uso más apropiado para get_posts es crear un array de envíos basados en un conjunto de parámetros. Los recupera en una lista de los envíos más recientes o aquellos que cumplan estos criterios. get_posts puede usarse también para crear múltiples bucles, aunque se prefiere usar una referencia más directa a new WP_Query de WP_Query WP_Query en este caso.

Los parámetros de get_posts son similares a aquellos de get_pages get_pages pero implementados bastante diferentemente, y deberían ser usados en los escenarios adecuados. get_posts usa WP_Query WP_Query, mientras que get_pages consulta la base de datos mas directamente. Cada cual tiene parámetros que reflejan esta diferencia de su implementación.

query_posts query_posts también usa WP_Query WP_Query, pero no se recomienda porque altera directamente el bucle principal al cambiar las variables de la variable global $wp_query. get_posts, por otro lado, simplemente referencia a un nuevo objeto WP_Query, y por lo tanto no afecta ni altera el bucle principal.

Si quisieras cambiar la consulta principal antes de que se ejecute, puedes invocarla usando pre_get_posts pre_get_posts. Si sólamente quisieras llamar un array de envíos basados en un pequeño y simple conjunto de parámetros dentro de una página, entonces get_posts es tu mejor opción.

Uso

 <?php $array_envíos get_posts$args ); ?> 

Uso por defecto

<?php $args = array(
	'posts_per_page'   => 5,
	'offset'           => 0,
	'category'         => '',
	'orderby'          => 'post_date',
	'order'            => 'DESC',
	'include'          => '',
	'exclude'          => '',
	'meta_key'         => '',
	'meta_value'       => '',
	'post_type'        => 'post',
	'post_mime_type'   => '',
	'post_parent'      => '',
	'post_status'      => 'publish',
	'suppress_filters' => true ); ?>
Nota: 'numberposts' (número de envios) y 'posts_per_page' (envíos por página) se pueden usar indistintamente.

Parámetros

Para una lista completa de parámetros mira WP_Query WP_Query.

Mira también get_pages() get_pages() para ejemplos del uso de parámetros.

get_posts() hace uso de la clase WP_Query WP_Query para recuperar los envíos. Mira the parameters section la sección de parámetros de la documentación de WP_Query para la lista de parámetros que acepta esta función.

Nota: get_posts usa suprimir filtros 'suppress_filters' ⇒ true por defecto, mientras que query_posts() query_posts() aplica filtros por defecto, esto puede ser confuso cuando se usan plugins que modifican las consultas (queries), como WPML. Nota también que incluso si 'suppress_filters' es cierto, aún se aplican cualesquier filtros adjuntados a pre_get_posts - sólo se suprimen los filtros ajuntados a 'posts_*' o 'comment_feed_*'.
Nota: El parámetro 'category' (categoría) necesita ser el ID de la categoría, y no su nombre.
Nota: El parámetro 'category' (categoría) puede ser una lista separada por comas de categorías, pues la función get_posts() pasa el parámetro 'category' (categoría) directamente a WP_Query como 'cat'.
'orderby'
(string) (optional) Ordena los envíos recuperados por el parámetro.
Default: 'date'
  • 'none' - No ordena (disponible desde la Versión 2.8).
  • 'ID' - Ordena por id de envío. Nota las mayúsculas.
  • 'author' - Ordena por autor.
  • 'title' - Ordena por titulo.
  • 'date' - Ordena por fecha.
  • 'modified' - Ordena por fecha de última modificación.
  • 'parent' - Ordena por id de envío/página padre.
  • 'rand' - Orden aleatorio.
  • 'comment_count' - Ordena por número de comentarios (disponible desde la Versión 2.9).
  • 'menu_order' - Ordena por Orden de Página. Usado más frecuentemente por Páginas (Campo de ordenación en la caja de Atributos de editar página) y por Adjuntos (los campos de enteros del diálogo de insertar/ cargar galería de medios), pero podrían ser usados para cualquier envío con distintos valores de 'menu_order' (orden de menú) (Todos son 0 por defecto).
  • 'meta_value' - Nota que 'meta_key=keyname' debe estar presente en la consulta. Nota también que la ordenación sera alfabética lo cual está bien para cadenas de texto, pero que puede ser inesperado para números (p.ej: 1, 3, 34, 4, 56, 6, etc, en vez de 1, 3, 4, 6, 34, 56 como hubieras naturalmente esperado ).
  • 'meta_value_num' - Ordena por meta valor numérico (disponible desde la Versión 2.8). También nota que 'meta_key=keyname' debe estar presente en la consulta. Este valor permite ordenación numérica como se menciona arriba en 'meta_value'.
Nota: get_pages() get_pages() usa el parámetro 'sort_column' (ordenar columna) en vez de 'orderby' (ordenar por). También, get_pages() get_pages() requiere que 'post_' sea antepuesto a estos valores: 'author (autor), date (fecha), modified (modificado), parent (padre), title (título), excerpt (extracto), content (contenido)'.
'post_mime_type'
(string o array) (Optional) Lista de tipos mime o cadena de texto separada por comas de tipos mime.
Default: None

Valor de retorno

(array) 
Lista de objetos de envío. Mira los valores de retorno de get_post()get_post().

a diferencia de get_pages()get_pages(), get_posts() retornará páginas privadas en el contexto adecuado (p. ej., para un administrador). (Mira: Andreas Kirsch, WordPress Hacking II, 24 de Enero 2009-- accedido el 09-11-2012.)

Ejemplos

Lista de envíos con desplazamiento

Si tienes tu sitio configurado para mostrar justo un envío en la página principal, pero también quieres listar enlaces a los 5 envíos previos en la categoría ID 1, puedes usar esto:

<ul>
<?php


$args = array( 'posts_per_page' => 5, 'offset'=> 1, 'category' => 1 );

$mis_envios = get_posts( $args );
foreach ( $mis_envios as $envio ) : setup_postdata( $envio ); ?>
	<li>
		<a href="<?php the_permalink(); ?>"><?php the_title(); ?></a>
	</li>
<?php endforeach; 
wp_reset_postdata();?>

</ul>
Nota: Con el uso del desplazamiento, la consulta superior debería ser solamente usada en una categoría que tenga más de un envío, de otro modo no habrá salida.

Envíos con navegación al previo y siguiente

Puedes usar también las consultas personalizadas para hacer la navegación a envíos previo y posterior. Aquí tienes el siguiente método para que funcione.

<?php
$mis_envios = get_posts('sort_column=menu_order&sort_order=asc');
$envios = array();
foreach ($mis_envios as $envío) {
   $envios[] += $envio->ID;
}

$actual = array_search(get_the_ID(), $envios);
$prevID = $envios[$actual-1];
$sigID = $envíos[$actual+1];
?>

<div class="navegacion">
<?php if (!empty($prevID)) { ?>
<div class="alineadoaIzq">
<a href="<?php echo get_permalink($prevID); ?>"
  title="<?php echo get_the_title($prevID); ?>">Previo</a>
</div>
<?php }
if (!empty($sigID)) { ?>
<div class="alineadoaDch">
<a href="<?php echo get_permalink($sigID); ?>" 
 title="<?php echo get_the_title($sigID); ?>">Siguiente</a>
</div>
<?php } ?>
</div><!-- .navegacion -->

Resetear tras listas de envíos con desplazamiento

Si necesitas tras el bucle, el envío que tuviste antes de comenzar el ciclado foreach, puedes usar esto:

<ul>
<?php
global $envio;
$args = array( 'posts_per_page' => 5, 'offset'=> 1, 'category' => 1 );
$mis_envios = get_posts( $args );
foreach ( $mis_envios as $envio ) : 
  setup_postdata( $envio ); ?>
	<li><a href="<?php the_permalink(); ?>"><?php the_title(); ?></a></li>
<?php endforeach;
wp_reset_postdata(); ?>
</ul>

Acceder a todos los datos del envío

Algunos datos relacionados con el envío no están disponibles por defecto para get_posts, tales como el contenido del envío mediante the_content()the_content(), o el ID numérico. Esto se resuelve llamando a una función interna llamada setup_postdata(), con el array de $envío como su argumento:

<?php
$args = array( 'posts_per_page' => 3 );
$mis_envíos = get_posts( $args );
foreach ( $mis_envíos as $envio ) :
  setup_postdata( $envio ); ?>
	<h2><a href="<?php the_permalink(); ?>"><?php the_title(); ?></a></h2>
	<?php the_content(); ?>
<?php endforeach; 
wp_reset_postdata(); ?>

Para acceder al ID del envío o el contenido sin llamar a setup_postdata(), o de echo a cualesquier datos específicos del envío (datos retenidos en the posts table la tabla de envíos o posts), puedes usar $envio->COLUMN, donde COLUMN es la columna de la tabla para los datos. Así que $envio->ID contiene el ID, $envio->post_content el contenido, y demás. Para mostrar o imprmir estos datos en tu página usa el comando echo de PHP, de este modo:

<?php echo $envio->ID; ?>

Últimos envíos ordenados por titulo

Para mostrar los últimos diez envíos ordenados alfabéticamente en orden ascendente, los siguiente mostrará sus fechas de publicación, título y extracto:

<?php
$args = array( 'posts_per_page' => 10, 'order'=> 'ASC', 'orderby' => 'title' );
$mis_envios = get_posts( $args );
foreach ( $mis_envios as $envio ) :
  setup_postdata( $envio ); ?> 
	<div>
		<?php the_date(); ?>
		<br />
		<?php the_title(); ?>   
		<?php the_excerpt(); ?>
	</div>
<?php
endforeach; 
wp_reset_postdata();
?>

Envíos aleatorios

Muestra una lista de 5 envíos seleccionados aleatoriamente usando la función RAND() de MySQL para le valor del parámetro orderby (ordenar por):

<ul>
<?php
$args = array( 'posts_per_page' => 5, 'orderby' => 'rand' );
$mis_envios = get_posts( $args );
foreach ( $mis_envios as $envio ) : 
  setup_postdata( $envio ); ?>
	<li><a href="<?php the_permalink(); ?>"><?php the_title(); ?></a></li>
<?php endforeach; 
wp_reset_postdata(); ?>
</ul>

Mostrar todos los adjuntos

Realiza esto fuera de cualesquier Loops bucles de tu plantilla.

<?php
$args = array( 'post_type' => 'attachment', 'posts_per_page' => -1, 'post_status' => 'any', 'post_parent' => null ); 
$mis_envios = get_posts( $args ); //envíos con adjunto
if ( $mis_envios ) {
	foreach ( $mis_envios as $envio ) {
		setup_postdata( $envio );
		the_title();
		the_attachment_link( $envio->ID, false );
		the_excerpt();
	}
	wp_reset_postdata();
}
?>

Mostrar adjuntos para el envío actual

Haz esto dentro del The Loop es:El bucle (donde $envio->ID está disponible).

<?php
$args = array( 'post_type' => 'attachment', 'posts_per_page' => -1, 'post_status' =>'any', 'post_parent' => $post->ID ); 
$mis_envíos = get_posts( $args ); //envíos con adjunto
if ( $mis_envíos ) {
	foreach ( $mis_envios as $adjunto ) {
		echo apply_filters( 'the_title' , $adjunto->post_title );
		the_attachment_link( $adjunto->ID , false );
	}
}
?>

Obtener un envío por su slug

Te permite conseguir el ID de un envío por su Slug de envío.

<?php
$el_slug = 'my-slug';
$args=array(
	'name' => $el_slug,
	'post_type' => 'post',
	'post_status' => 'publish',
	'posts_per_page' => 1
);
$mis_envios = get_posts( $args );
if( $mis_envios ) {
	echo 'ID del primer envío encontrado ' . $mis_envios[0]->ID;
}
?>

Parámetros de Taxonomía

Muestra los envíos asociados a cierta taxonomía. Cuando se especifique una taxonomía registrada a un tipo de envío personalizado entonces en vez de usar 'categoría' usa '{nombre_de_taxonomía_personalizada}'. Por ejemplo, si tuvieras una taxonomía personalizada llamada "genero" y quisieras mostrar sólamente los envíos de genero "jazz" usarías e código siguiente.

<?php
$args = array(
	 'posts_per_page' => 8,
	 'orderby' => 'rand',
	 'post_type' => 'albums',
	 'genre' => 'jazz',
	 'post_status' => 'publish'
);
$mis_envios = get_posts( $args ); //para mostrar álbumes
?>

El siguiente ejemplo enseña envíos etiquetados con 'jazz', bajo la taxonomía personalizada de 'genre', usando 'tax_query':

$args = array(
	'tax_query' => array(
		array(
			'taxonomy' => 'genre',
			'field' => 'slug',
			'terms' => 'jazz'
		)
	)
);
$mis_envios = get_posts( $args ); //para mostrar los de jazz

Consulta the taxonomy parameters section la sección de parámetros de taxonomía de la documentación de WP_Query para más ejemplos.

Parámetros de campos personalizados

Muestra los envíos asociados con cierto campo personalizado. El siguiente ejemplo enseña envíos de tipo de envío 'producto' que tiene la meta clave 'caracterizado' con el valor 'si', usando 'meta_query':

$args = array(
	'post_type' => 'producto',
	'meta_query' => array(
		array(
			'key' => 'caracterizado',
			'value' => 'si',
		)
	)
 );
$mis_envios = get_posts( $args );

Consulta the custom fields parameters section la sección de parámetros de campos personalizados de la documentación de WP_Query para más ejemplos.

Log de cambios

Fichero fuente

get_posts() se ubica en wp-includes/post.php.

Relacionado

Mira también el índice de referencia de funciones y el índice de etiquetas de plantilla.