WP-DOC

Pisanie motywu

06.09 WP_Query

Ostatnia modyfikacja: 15.09.2021

Dodanie WP_Query do standardowej pętli Loop

WP_Query to klasa pozwalająca na modyfikowaniu zapytania, które wykonuje standardowa pętla WordPress – Loop. W zależności od tego w jakim pliku znajduje się pętla, wykonuje odpowiednie zapytanie do bazy danych. Przykładowo pętla znajdująca się w pliku category.php – będzie wyświetlać wpisy z danej kategorii. Natomiast pętla w pliku single.php – będzie wyświetlać pojedynczy wpis na blogu. Zanim zaczniemy korzystać z klasy WP_Query, poniżej wygląd standardowej pętli Loop.

Standardowa pętla Loop

<?php
if (have_posts()) :
    while (have_posts()) : the_post();
        // Wyświetlanie treści przez pętle WordPress
    endwhile;
else : 
    // Tutaj akcje, jeżeli nie istnieje żaden post.
endif;
?>

Do wyżej przedstawionego kodu dodajmy zmienną o przykładowej nazwie $new_query, a następnie przypiszmy do nie klasę WP_Query, jeszcze bez jakichkolwiek argumentów. Następnie za pomocą zmiennej $new_query zmodyfikujemy standardowe zapytanie zapytanie pętli Loop.

Modyfikacja standardowej pętli Loop

<?php
$new_query = new WP_Query()
if ($new_query->have_posts()) :
    while ($new_query->have_posts()) : $new_query->the_post();
        // Wyświetlanie treści przez pętle WordPress
    endwhile;
else : 
    // Tutaj akcje, jeżeli nie istnieje żaden post.
endif;
?>

Przywracanie zapytania do pierwotnej postaci

Jeżeli modyfikujemy standardowe zapytanie pętli Loop za pomocą WP_Query, to za tą pętlą, należy przywrócić ją do standardowego zapytania. Jest bardzo ważne, jeżeli klasę tą wykorzystujemy na przykład w wtyczce lub pętla występuje kilkukrotnie w jednym pliku, na przykład na stronie głównej witryny firmowej. Do przywrócenia pętli do standardowego zapytania posłuży funkcja wp_reset_postdata(), jak zaprezentowano na listingu niżej.

Przywracanie zapytania do standardowej postaci

<?php
$new_query = new WP_Query()
if ($new_query->have_posts()) :
    while ($new_query->have_posts()) : $new_query->the_post();
        // Wyświetlanie treści przez pętle WordPress
    endwhile;

    wp_reset_postdata();

else : 
    // Tutaj akcje, jeżeli nie istnieje żaden post.
endif;
?>

Różnica między standardową pętlą, a tą modyfikowaną za pomocą klasy WP_Query to:

  • standardowa pętla WordPress opiera się na adresie URL i jest inicjowana przed przetworzeniem motywu strony;
  • zapytanie zmodyfikowane za pomocą klasy WP_Query, jest wykonywane wewnątrz motywu lub wtyczki.

Pętla korzystająca z klasy WP_Query, wpływa na zmienna globalną $post, która jest używana przez tagi motywu. Funkcja wp_reset_postdata(), przywraca zmienną globalną $post do bieżącego zapytania, używanej przez WP_Query().

Argumenty WP_Query

Klasa ta jako argument przyjmuje zmienną, która jest tablicą, w której podajemy parametry i ich wartości. Poniższy przykład wyświetli wpisy z kategorii numer 4, a ich ilość będzie ograniczona do 3 wpisów.

Przykład WP_Query z parametrami i wartościami

<?php
$new_query = new WP_Query(
    array (
        'cat' => 4, // wpisy z kategorii numer 4
        'posts_per_page' => 3 // ilość wpisów z kategorii
    )
)
if ($new_query->have_posts()) :
    while ($new_query->have_posts()) : $new_query->the_post();
        // Wyświetlanie treści przez pętle WordPress
    endwhile;

    wp_reset_postdata();

else : 
    // Tutaj akcje, jeżeli nie istnieje żaden post.
endif;
?>

Jeżeli korzystasz z parametru posts_per_page, która służy do wyświetlania ilości postów, wówczas dla tej pętli pomijana jest wartość ilości wyświetlanych wpisów, która ustawiona jest w panelu administratora WordPress. Wartość ta jest ustawiana w USTAWIENIA => USTAWIENIA CZYTANIA.

Lista parametrów klasy WP_Query

Pełna lista parametrów znajduje się w oficjalnej dokumentacji WordPress WP_Query. Zachęcam do jej przejrzenia, gdyż lista jest bardzo długa, a co za tym idzie, daje to bardzo dużo możliwości. Natomiast poniżej kilka parametrów z oficjalnej dokumentacji.

Parametry autora

  • autor – [int] – identyfikator autora (ID)
  • autor_name – [string] – należy użyć user_nicename – nie nazwy
  • autor__in – [array] – należy użyć identyfikatora autora
  • autor__not_in – [array] – należy użyć identyfikatora autora

Parametry autora – przykłady wykorzystania

<?php
// Wyświetlanie postów autora o numerze identyfikatora (ID)
$new_query = new WP_Query(array('author' => 4));

// Wyświetlanie postów autora używając user_nicname
$new_query = new WP_Query(array('author_name' => 'maciej'));

// Wyświetlanie postów kilku wybranych autorów
$new_query = new WP_Query(array('author' => '4,8,15,17'));

// Wyświetlanie postów wszystkich autorów oprócz wybranego jednego (przed numerem identyfikatora stawiamy znak minus)
$new_query = new WP_Query(array('author' => -15));

// Wyświetlanie postów wielu autorów
$new_query = new WP_Query(array('author__in' => array(4,8,15,17)));

// Wyświetlanie postów wszystkich autorów oprócz tych podanych w tablicy
$new_query = new WP_Query(array('author__in' => array(8,17)));
?>

Parametry kategorii

  • cat – [int] – identyfikator kategorii (ID)
  • category_name – [string] – należy podać slug kategorii
  • categoryy__and – [array] – identyfikator kategorii
  • category__in – [array] – identyfikator kategorii
  • category__not_in – [array] – identyfikator kategorii

Parametry kategorii – przykłady wykorzystania

<?php
// Wyświetlanie postów kategorii o numerze identyfikatora (ID), oraz elementy podrzędne
$new_query = new WP_Query(array('cat' => 4));

// Wyświetlanie postów, które mają kilka kategorii używając identyfikatora
$new_query = new WP_Query(array('cat' => '4,8,15,17'));

// Wyświetlanie postów, wszystkich kategorii, które są poprzedzone minusem
$new_query = new WP_Query(array('cat' => '-4,-8,-15'));

// Wyświetlanie postów kategorii używając slug, oraz elementy podrzędne
$new_query = new WP_Query(array('cat_name' => 'obiady'));

// Wyświetlanie postów które mają te kategorie używając slug
$new_query = new WP_Query(array('cat_name' => 'obiady,kolacje'));

// Wyświetlanie postów które mają wszystkie z wymienionych kategorii używając slug
$new_query = new WP_Query(array('cat_name' => 'obiady+kolacje'));

// Wyświetlanie postów z kilku kategorii o numerze identyfikatora
$new_query = WP_Query(array('category__end' => array(4,8,15,17)));

// Wyświetlanie postów kategorii o numerze identyfikatora (bez elementów podrzędnych)
$new_query = new WP_Query(array('category__in' => 4));

// Wyświetlanie postów z kilku kategorii o numerze identyfikatora (bez elementów podrzędnych)
$new_query = new WP_Query(array('category__in' => array(4,8,15,17)));

// Wyświetlanie postów z wszystkich kategorii oprócz tych podanych w tablicy
$new_query = new WP_Query(array('category__not_in' => array(4,15)));
?>

Parametry typu wpisu

  • post_type – [string/array] – typ wpisu. Pobiera posty według typu. Domyślna to post.
    • post – post
    • page – strona
    • revision – zmiana
    • attachment – załącznik, więcej w dokumentacji
    • nav_menu_item – pozycja menu nawigacyjnego
    • any – dowolny typ – niestandardowe typy postów (np. filmy)

Parametry typu postu – przykłady wykorzystania

<?php
// Wyświetlania tylko strony
$new_query = new WP_Query(array('post_type' => 'page'));

// Wyświetlaj posty oraz niestandardowe typy postów
$args = array('post_type' => array('post','filmy','muzyka','ksiazki'));
$new_query = new WP_Query($args);
?>

Parametry stanu wpisu

  • post_status – [string/array] – status posta – domyślna wartość to opublikowany publish
    • publish – post lub strona opublikowana
    • pending – post oczekujący na sprawdzenie
    • draft – wersja robocza
    • auto-draft – nowo utworzony post bez treści
    • future – post do opublikowania w przyszłości
    • private – niewidoczna dla niezalogowanych użytkowników
    • inherit – zmiana
    • trash – post w koszu
    • any – pobiera dowolny status z wyjątkiem inherit, trash oraz auto-draft.

Parametry stanu wpisu – przykłady wykorzystania

<?php
// Wyświetlania posty, które są szkicami
$new_query = new WP_Query(array('post_status' => 'draft'));

// Wyświetlanie postów o różnych statusach
$args = array('post_status' => array('pending', 'draft', 'future'))
$new_query = new WP_Query($args);
?>

Wybrane parametry

Ze względu na dużą ilość parametrów jaką dysponuje klasa WP_Query, ograniczyłem przedstawienie tylko do kilku z nich wraz z przykładami. Jeszcze raz zachęcam do przejrzenia oficjalnej dokumentacji, aby poznać więcej parametrów. Poniżej lista wybranych parametrów klasy bez podziału na kategorii.

  • tag – [string] – slug tagu
  • tag_id – [int] – identyfikator tadu
  • tag__in – [array] – identyfikator tagu (DI)
  • p – [int] – identyfikator postu
  • name – [string] – slug postu
  • page_id – [int] – identyfikator strony
  • pagename – [string] – slug strony
  • post__in – [array] – identyfikator postu (ID)
  • posts_per_page – [int] – ilość postów do wyświetlenia na stronie, wartość -1 wyświetla wszystkie posty
  • order – typ sortowania domyślnie DESC
    • ASC – od najmniejszej do największej (1,2,3,4)
    • DESC – od największej od najmniejszej (4,3,2,1)
  • orderby – parametry sortowania, domyślnie post_date
    • id – [int] – numer identyfikatora posta (ID)
    • date – sortowanie według daty
    • name – sortowanie według nazwy posta
    • modified – według daty ostatniej modyfikacji
    • rand – kolejność losowa
    • comment_count – sortowanie według liczby komentarzy
    • post__in – [array] – sortowanie nastąpi według ID postów zdeklarowanej w tablicy
  • year – [int] – wyświetla posty według roku w postaci 4-cyfrowej na przykład 2021
  • monthnum – [int] – wyświetla posty według miesiąca, numery od 1 do 12
  • day – [int] – wyświetla posty według dnia , numery od 1 do 31
  • date_query – [array] – parametry daty
    • year – [int] – według roku w postaci 4-cyfrowej, na przykład 2021
    • monthum – [int] – według miesiąca, numery od 1 do 12
    • day – [int] – według dnia, numery od 1 d o31

Wyprane parametry – przykłady zastosowania

<?php
// Wyświetlania posty, które zawierają tag o nazwie slug
$new_query = new WP_Query(array('tag' => 'gotowanie'));

// Wyświetlania posty, które zawierają tag o numerze identyfikatora (ID)
$new_query = new WP_Query(array('tag_id' => 14));

// Wyświetlania posty, które zawierają tag o numerze identyfikatora (ID)
$new_query = new WP_Query(array('tag__in' => array(8,14,16)));

// Wyświetlania post numerze identyfikatora (ID)
$new_query = new WP_Query(array('p' => 7));

// Wyświetlania post o nazwie slug
$new_query = new WP_Query(array('name' => 'szybkie-gotowanie'));

// Wyświetlania stronę o numerze identyfikatora (ID)
$new_query = new WP_Query(array('page_id' => 8));

// Wyświetlania posty o podanych numerach identyfikatora (ID)
$new_query = new WP_Query(array('post__in' => array(5,14,18,29)));

// Wyświetlania stronę o nazwie slug
$new_query = new WP_Query(array('pagename' => 'kontakt'));

// Ustawia ilość postów do wyświetlenia na stronie
$new_query = new WP_Query(array('post_per_page' => 3));

// Wyświetlanie postów według trybu sortowania (od najnowszego według nazwy posta)
$new_query = new WP_Query(array(
    'order'   => 'DESC',
    'orderby' => 'name'
));

// Wyświetlanie losowego posta
$new_query = new WP_Query(array(
    'orderby'       => 'rand',
    'posts_per_page' => 1
));

// Wyświetlanie postów według ID postów zdeklarowanych w tablicy
$new_query = new WP_Query(array(
    'post__in' => array(84,14,35),
    'orderby'  => 'post__in'
));

// Wyświetlanie postów z określonej daty
$new_query = new WP_Query('year=2021&monthnum=05&day=13');

// lub

$new_query = new WP_Query(array(
    'data_query' = > array(
        array(
            'year'     => 2021,
            'monthnum' => 12,
            'day'      => 13
        ),
    ),
));

?>

Mieszanie parametrów

Wykorzystując kilka parametrów jednocześnie, możemy uzyskać praktycznie dowolny zestaw postów lub stron o interesujących nas parametrach. Poniższy przykład wyświetli:

  • tylko i wyłącznie wpisy
  • z roku 2021
  • z miesiąca sierpień
  • o okrślonej kategorii
  • ilość wpisów to 6

Dowolne zestawienie parametrów klasy WP_Query

<?php
$args = array(
    'post_type'     => 'post',
    'data_query'    => array(
        array(
            'year'     => 2021,
            'monthnum' => 8
        ),
    ),
    'cat'           => 4,
    'posts_per_page' => 6
);

$new_query = new WP_Query($args);
?>

Kolejność podawania parametrów dla klasy WP_Query jest absolutnie dowolna.

KOMENTARZE

Jeżeli masz pytanie lub sugestie dotyczącą artykułu to napisz komentarz. Wartościowe komentarze zostaną umieszczone jako opinie warte uwagi.

Napisz komentarz

Wszystkie pola są obowiązkowe. E-mail nie będzie udostępniony, ani wykorzystywany do rozsyłania wiadomości reklamowych.

Jeszcze nikt nie napisał komentarza.