Використання запитів WP_Query у WordPress — частина 2 (огляд циклу)

Цей урок є продовженням серії про роботу з запитами до бази даних WP_Query у ВордПрес. В ньому ми зосередимось на використанні та правильному підходу до циклів у запиті: зокрема розглянемо важливість циклу, основні способи роботи з ним, використання декількох циклів, а також подивимось на найбільш популярні функції отримання даних всередині циклу.

Що таке цикл і навіщо він потрібен?

Без циклу на сторінці вашого сайту нічого не буде показуватись (з результатів запиту). Після того, як WordPress виконає запит, йому необхідно явно вказати, що потрібно показувати з тих даних, які він отримав у цьому запиті. І саме тут на сцену виходить цикл.

Цикл пов’язаний з вашим запитом і для своєї роботи опирається на три основних моменти:

умовна перевірка if( $query->have_posts() ) перевіряє, чи є у результаті запиту якісь публікації (пости, сторінки, тощо). Вона бере значення властивості post_count з нашого запиту і порівнює із значенням умови current_post + 1.
цикл while( $query->have_posts() ) проходить циклом по кожній публікації, яка є в масиві отриманих результатів запиту. В цьому методі автоматично йде перемотка циклу, опираючись на змінні та властивості, що вказані в попередньому пункті. Це без зайвих кроків з нашого боку (як програмістів) дає нам змогу виявляти наявність публікацій в циклі.
конструкція $query->the_post() отримує доступ до конкретної публікації в масиві. На додачу вона працює з лічильником в масиві, а також налаштовує глобальні дані публікації.

Зауважте, що ви повинні викликати метод have_posts() лише всередині циклу, в іншому випадку ви застрягнете в нескінченному циклі!

Ось як виглядає застосування класу WP_Query у поєднанні з циклом:

<?php
$args = array(
  // масив аргументів для запиту
);
// створення нового екземпляру класу – нового об’єкту, запиту
$query = new WP_Query( $args );
// перевірка на наявність результатів для цього запиту
if ( $query->have_posts() ) {
  // проходження циклом по результатам запиту
  while ( $query->have_posts() ) {
    $query->the_post();
    // тут контент публікації результату
  }
}
// обов'язкове відновлення (скидання) глобальної змінної $post
wp_reset_postdata();
?>

Після обробки циклу залишається тільки навести порядок з допомогою wp_reset_postdata().

Яку структуру може мати цикл

Цикл можна структурувати у різний спосіб, що залежить в основному від того, які дані публікації вам потрібно показувати. Нижче представлено практичний приклад циклу, з допомогою якого ми можемо показати назву публікації (її заголовок), прикріплене зображення (featured image, thumbnail, міні-зображення посту) та короткий опис (уривок, excerpt) у вигляді макету card з фреймворка Bootstrap. Такий цикл можна було б використати на архівній сторінці певних публікацій:

<?php
$args = array(
  // масив аргументів для запиту
);
// створення нового екземпляру класу – нового об’єкту, запиту
$query = new WP_Query( $args );
?>
<div class="row row-cols-1 row-cols-md-3 g-4">
<?php
  // перевірка на наявність результатів для цього запиту
  if ( $query->have_posts() ) {
    // проходження циклом по результатам запиту
    while ( $query->have_posts() ) {
      $query->the_post();
      // далі йде показ контенту кожної окремої публікації
      ?>
      <div id="post-<?php the_ID(); ?>" <?php post_class('card'); ?>>
        <a href="<?php the_permalink(); ?>" title="<?php the_title_attribute(); ?>">
          <?php the_post_thumbnail('thumbnail', array('class' => 'card-img-top')); ?>
          <div class="card-body">
            <h3 class="card-title"><?php the_title(); ?></h3>
            <div class="card-text"><?php the_excerpt(); ?></div>
          </div>
        </a>
       </div>
     <?php }
  } ?>
</div>
<?php
// відновлення даних глобальної змінної $post
wp_reset_postdata();
?>

Приклад такого циклу відображає саме те, про що сказано вище: міні-картинку публікації, заголовок та уривок у форматі контейнеру картки (card), стилізованої фреймворком Bootstrap.

Опрацювання даних всередині циклу

Як видно з попереднього прикладу, ми перевіряємо лише умову наявності публікацій у результаті запиту. Але всередині циклу, ми не перевіряємо дані. Для цього прикладу можна було б додати окрему перевірку, чи має публікація «приліплене зображення» (featured image), оскільки такі ситуації дуже часті. Для цього достатньо огорнути елемент картинки у тег if, наприклад, так:

<?php
…
  // перевіряємо, чи призначено публікації картинку мініатюру
  // якщо так – тоді показуємо її, інакше – нічого не показувати
  if ( has_post_thumbnail() ) {
    the_post_thumbnail('thumbnail', array('class' => 'card-img-top'));
  }
…
?>

Що робити, якщо мені потрібно запустити кілька циклів (запитів)?

Зауважте, що ви можете використовувати запит WP_Query багато разів, але для цього вам потрібно скидати глобальні дані та запускати кожного разу новий окремий екземпляр класу WP_Query.

Нижче показано зразок використання кількох запитів до бази даних WP_Query на одній сторінці: спочатку отримуємо одну публікацію із типом post (допис), а в другому запиті показуємо список ul із постами окрім першого:

<?php
// аргументи першого запиту
$args1 = array(
  'post_type' => 'post',
  'posts_per_page' => '1'
);
// перший запит
$query1 = new WP_Query( $args1 );
// перевірка на наявність результатів для цього запиту
if ( $query1->have_posts() ) {
  // проходження по циклу результатів
  while ( $query1->have_posts() ) {
    $query1->the_post();
    ?>
    <div id="post-<?php the_ID(); ?>" <?php post_class('card'); ?>>
      <a href="<?php the_permalink(); ?>" title="<?php the_title_attribute(); ?>">
        <?php the_post_thumbnail('thumbnail', array('class' => 'card-img-top')); ?>
        <div class="card-body">
          <h3 class="card-title"><?php the_title(); ?></h3>
          <div class="card-text"><?php the_excerpt(); ?></div>
        </div>
      </a>
     </div>
    <?php
  }
}
// відновлення даних глобальної змінної $post
wp_reset_postdata();
////////////////////////////////////////////////////////////////////////////
// аргументи другого запиту
$args2 = array(
  'offset' => '1',
  'post_type' => 'post'
);
// другий запит
$query2 = new WP_Query( $args2 );
// перевірка на наявність результатів для цього запиту
if ( $query2->have_posts() ) {
  echo '<ul class="more-posts">';
  // проходимо по циклу результатів
  while ( $query2->have_posts() ) {
    $query2->the_post();
    ?>
    <li <?php post_class(); ?>>
      <a href="<?php the_permalink(); ?>" title="<?php the_title_attribute(); ?>">
        <?php the_title(); ?>
      </a>
    </li>
    <?php
  }
  echo '</ul>';
}
// відновлення даних глобальної змінної $post
wp_reset_postdata();
?>

Зверніть увагу на два аргументи у запитах:

аргумент 'posts_per_page' => '1' у першому запиті позначає показ лише одного результату, та дефолтно найсвіжішої публікації (останньої у базі даних).
аргумент 'offset' => '1' у другому запиті показує ту кількість публікацій, яка вказана в налаштуваннях сайту та пропускає першу публікацію (яку ми вже отримали із першим запитом).

Подібним чином ви можете створити на сторінці стільки запитів з класом WP_Query, скільки вам буде потрібно. Але зауважте, що занадто багато запитів — це не надто гарна ідея. Натомість, краще створити для цього окремі сторінки, про що я писав у попередньому вступному уроці серії про запити WP_Query.

До яких даних публікації у мене є доступ всередині циклу?

Існує багато функцій з доступом до даних публікації, які можна викликати всередині циклу, включно з дефолтними даними, а також кастомними мета-даними (доданими вами мета-полями до постів). Таких функцій багато, але давайте розглянемо найбільш вживані:

Назва публікації (її заголовок). Є три основні функції, з допомогою яких ви можете отримати заголовок публікації: the_title(), get_the_title() і the_title_attribute(). Функція get_the_title() просто отримує назву публікації без додаткових параметрів, тоді як the_title() може відображати додаткову розмітку разом з заголовком. Функція the_title_attribute() робить додатково «html-очистку» заголовку перед його показом.
Уривок контенту (короткий зміст). Для цього існує спеціальна функція the_excerpt(). Вона «фільтрує» контент, щоб він правильно відображався читачам. Додатково, оскільки не кожна публікація володіє окремо визначеним автором уривком, функція сама створить скорочену версію контенту публікації перед її показом. Натомість, щоб відобразити весь контент публікації, скористайтеся функцією the_content().
Таксономія публікації (наприклад, її категорії, теги чи інші метадані). Публікації можуть мати одну, або декілька категорій, тегів, тощо. Скористайтеся функціями the_category(), щоб відобразити список категорій публікації, та the_tags() для тегів. Функція the_author() покаже автора поточної публікації у циклі. А щоб отримати (зробити echo) ідентифікатор публікації, використайте функцію the_ID().
Отримати дату та час публікації. Двигун CMS WordPress володіє спеціальними функціями, які ви можете використовувати в циклі для відображення дати публікації (the_date()) і часу (the_time()) публікації.
Мініатюра публікації. Для виведення повного тегу картинки (<img …>), що «приліплена» до поточного посту в циклі, використовуйте функцію the_post_thumbnail().

Сьогодні ми розглянули кілька практичних прикладів роботи з циклами, що знадобляться вам при побудові запитів до бази даних. В подальших уроках ми продовжимо дослідження запитів класом WP_Query у ВордПрес.

Теги: WordPress