У сьогоднішній статті з нашої серії, присвяченій вивченню класу WP_Query, ви дізнаєтеся про декілька аргументів, які можна використовувати разом з WP_Query для здійснення запитів до:

  • статусу;
  • порядку;
  • пагинации.

Ці аргументи можна використовувати для одержання записів з бази даних у запитах до вкладень, для зміни порядку сортування записів, а також зазначення їх кількості для виводу на екран, і багато чого іншого.

Згадуємо, як працюють аргументи в WP_Query

Коли ви використовуєте WP_Query у власних темах оформлення або плагінах, доводиться включати код чотири основних елемента:

  • Аргументи для запиту, в яких використовуються параметри;
  • Сам запит;
  • Цикл;
  • Завершальний етап: скидання даних запису.

На практиці це виглядає наступним чином:

have_posts() ) {
// початок циклу обробки даних з результатів запиту
while ( $query->have_posts() ) {
$query->the_post();
// вміст опитуваної запису
}
}
// відновлення вихідних даних запису
wp_reset_postdata();
?>

Аргументи повідомляють WordPress, які дані потрібно отримувати з бази даних. Давайте зосередимо увагу на самому початку коду:

$args = array(
// Аргументи для вашого запиту
);

Як видно, аргументи укладені в масив.

Створюємо код для аргументів

Існує певний синтаксис ініціалізації аргументів в масиві:

$args = array(
‘parameter1’ => ‘value’,
‘parameter2’ => ‘value’,
‘parameter3’ => ‘value’
);

Вам слід укладати параметри та їх значення в одинарні лапки, а також використовувати => між ними. Аргументи розділяються комою. Якщо не дотримуватися встановлений синтаксис, то WordPress може опитати не всі наведені вами аргументи, і в результаті на екран нічого не виведеться.

Параметри статусу

Як ви знаєте, WordPress задає кожного запису окремий статус. Можна використовувати параметр post_status для запитів записів з одним або кількома статусами.

Доступні наступні аргументи:

  • publish: опублікований запис або сторінка;
  • pending: запис очікує розгляду;
  • draft: запис в статус чорновика;
  • auto-draft: тільки що створена запис, без будь-якого контенту;
  • future: запланована запис;
  • private: запис не видно відвідувачам, які не авторизувалися на сайті;
  • inherit: змінена версія запису або статус для прикріплених записів;
  • trash: запис знаходиться в кошику;
  • any: запит будь статус, за винятком тих, у яких параметр ‘exclude_from_search’ виставлений на true (наприклад, auto-draft або trash).

Якщо ви не вкажете статус в аргументах вашого запиту, WordPress за замовчуванням буде орієнтуватися на publish; якщо користувач авторизований на сайті, то в запиті також будуть враховуватися записи зі статусом private. Якщо ви запускаєте запит від імені адміністратора, то WordPress також буде враховувати захищені статуси: future, draft і pending.

Припустимо, що у вас є сайт-афіша, на якому використовується власний тип записів event, і в якості дати публікації використовується дата, на яку заплановано той чи інший захід. За замовчуванням WordPress не буде відображати ще не відбулися події. Незважаючи на те, що ви запланували, дата публікації перебуває в майбутньому, а, значить, статус запису буде future.

Щоб обійти цю проблему, можна використовувати такі аргументи:

$args = array(
‘post_type’ => ‘event’,
‘post_status’ => ‘future’
);

Цей код дозволить відобразити ті події, які ще не відбулися, так як для опублікованих записів використовується статус publish. Але якщо необхідно показати і відбулися заходи, то потрібно використовувати масив, в якому зазначено більше одного статусу:

$args = array(
‘post_type’ => ‘event’,
‘post_status’ => array(
‘future’,
‘publish’
)
);

Параметр post_status важливий при здійсненні запитів до вкладень, тому що використовується статус inherit, а не publish. Щоб здійснити запит усіх вкладень, можна використовувати наступний код:

$args = array(
‘post_type’ => ‘attachment’,
‘post_status’ => ‘inherit’
);

Але ви можете замінити inherit на будь-який інший статус, який дозволить отримати аналогічний результат.

Параметри сортування

Існує два параметри, які можна використовувати для сортування записів, отриманих за допомогою WP_Query: order і orderby. Як ви вже зрозуміли, order визначає порядок, у якому записи виводяться в циклі, а orderby визначає, по якому полю у базі даних вони будуть сортуватися.

Параметр order

Є всього аргументу, які можна використовувати для сортування:

• ASC: зростання (1, 2, 3; a, b, c).
• DESC: за спаданням (3, 2, 1; c, b, a).

Якщо ви не включіть аргумент для order, за замовчуванням WordPress буде використовувати DESC.

Параметр orderby

Ви можете сортувати записи по декільком полям:

  • none: немає умов сортування (доступно з версії 2.8);
  • ID: сортування по id запису. Не забувайте про верхній регістр;
  • author: сортування по автору;
  • title: сортування по заголовку;
  • name: сортування за slug запису;
  • type: сортування за типом запису;
  • date: сортування за датою;
  • modified: сортування по даті останньої зміни;
  • parent: сортування по id батьківської запису/сторінки;
  • rand: випадковий порядок;
  • comment_count: сортування за кількістю коментарів;
  • menu_order: сортування за порядком розташування сторінок. Найбільш часто використовується для сторінок (тут використовується значення, яке вказується в мета-блоці при редагуванні сторінки), а також для вкладень (використовується ціле число з діалогового вікна Вставка / Завантажити медиафайл). Також можна використовувати для будь-якого типу запису з включеним параметром menu_order;
  • meta_value: сортування за значенням мета-ключа або користувача;
  • поля: Буде працювати тільки в тому випадку, якщо встановлено параметр meta_key. Мета-значення сортуються за алфавітом, а не за числами (тобто 34 виведеться раніше цифри 4);
  • meta_value_num: сортування по числовому мета-значенням. Як і у випадку з meta_value, у запиті має використовуватися аргумент meta_key;
  • post__in: зберігає сортування по ID записів, виставлену в масиві post__in.

За замовчуванням, для сортування використовується поле date. Тобто, сортується за датою публікації.

Якщо потрібно відсортувати записи по заголовку в порядку убування, то можна використовувати такі аргументи:

$args = array(
‘orderby’ => ‘title’,
‘order’ => ‘ASC’
);

Сортування по декількох полях

Щоб відсортувати записи за кількома полями, потрібно скористатися масивом з параметром orderby і з параметром order, якщо потрібна сортування кожного поля в різному порядку.

Припустимо, що у вас є довільне поле ratings, яке ви хочете використовувати для сортування в інтернет-магазині. Ви можете здійснити сортування за зростанням рейтингу, а потім по заголовку за допомогою наступного коду:

$args = array(
‘orderby’ => array(
‘meta_value_num’,
‘title’
),
‘order’ => ‘ASC’,
‘meta_key’ => ‘rating’
);

Я включила в запит аргумент meta_key, і це дозволить WordPress зрозуміти, яке довільне поле ми використовуємо. Це потрібно робити саме тому, що WordPress зберігає метадані записів у таблиці wp_postmeta, а не в wp_posts.

Але що якщо потрібно виконати сортування за спаданням рейтингу, а потім по заголовку в порядку зростання? У такому разі слід використовувати інший масив:

$args = array(
‘orderby’ => array(
‘meta_value_num’,
‘title’
),
‘order’ => array(
‘DESC’,
‘ASC’
),
‘meta_key’ => ‘rating’
);

Також можна виконати сортування за кількома полями, якщо не потрібно використовувати метадані запису. Наприклад, щоб сортувати записи за типом, а потім по даті, можна використовувати наступний код:

$args = array(
‘orderby’ => array(
‘type’,
‘date’
),
‘order’ => array(
‘ASC’,
‘DESC’
)
);

Цей код дозволить здійснити сортування за типом запису у зростаючому порядку, а потім, в рамках кожного типу записів, по даті в порядку убування.

Параметри пагинации

Ми переходимо до ще одного набору параметрів, який пов’язаний з посторінковим висновком контенту, з пагінація. Ці установки допомагають визначати, скільки записів буде опитано, і як буде відбуватися нумерація сторінок.

Доступні наступні параметри:

  • nopaging (boolean): відображати всі записи, або використовувати пагінацію. За замовчуванням виставлене значення ‘false’, тобто, використовується посторінковий висновок;
  • posts_per_page (int): кількість записів на сторінці;
  • posts_per_archive_page (int): кількість записів на сторінці, але тільки на сторінці архіву;
  • offset (int): кількість записів, після якого починається висновок;
  • paged (int): сторінка в архіві, з якого виводяться сторінки;
  • page (int): кількість сторінок для статичної головної сторінки. Відображення записів, які повинні у звичайному режимі відображатимуться на сторінці Х при включенні статичною головної сторінки (Front Page);
  • ignore_sticky_posts (boolean): ігноруємо прикріплені запису. За замовчуванням використовується значення false.

Кількість записів і пропуск записів

Щоб показати п’ять самих свіжих записів, використовуємо наступний код:

$args = array(
‘posts_per_page’ => ‘5’
);

Показуємо п’ять самих свіжих записів, за винятком самої останньої опублікованій:

$args = array(
‘posts_per_page’ => ‘5’,
‘offset’ => ‘1’
);

Врахуйте, що, незважаючи на те, що ви витягаєте запису з шести останніх записів у базі даних, ви використовуєте ‘posts_per_page’ => ‘5’, так як саме така кількість записів повинно бути відображено.

Можна створити два запиту: один для відображення самих свіжих записів, а другий – для відображення ще 10 записів, за винятком тієї запису:

$args = array(
‘posts_per_page’ => ‘1’
);
// Тут починається запит і цикл, а також скидання записів.
$args = array(
‘posts_per_page’ => ’10’,
‘offset’ => ‘1’
);
// Тут йде другий запит, цикл, і скидання.

Для відображення всіх записів можна використовувати posts_per_page:

$args = array(
‘posts_per_page’ => ‘-1’
);

Прикріплені запису

Зазвичай прикріплені записи відображаються першими в будь-якому запиті. Якщо потрібно змінити цю установку, то скористайтеся параметром ignore_sticky_posts:

$args = array(
‘posts_per_page’ => ‘5’,
‘ignore_sticky_posts’ => true
);

Наведені вище аргументи дозволять отримати останні п’ять записів, незалежно від того, є вони прикріпленими чи ні.

Якщо потрібно відобразити тільки прикріплені запису, то потрібно використовувати функцію get_option() і аргумент post__in наступним чином:

$sticky = get_option( ‘sticky_posts’ );
$args = array(
‘posts_per_page’ => ‘5’,
‘post__in’ => $sticky
);

Наведений вище код дозволить отримати п’ять останніх прикріплених записів. Якщо їх буде менше п’яти (наприклад, три), то буде виведено лише доступне кількість прикріплених записів.

Пагинация в архівах

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

Наприклад, наступний код можна використовувати на сторінці архіву, щоб вивести по 20 записів на кожну сторінку:

$args = array(
‘posts_per_archive_page’ => ’20’
);

Примітка: аргумент posts_per_archive_page перевизначає posts_per_page.

Також можна вивести ті сторінки, які повинні відображатися на певній сторінці з пагинации. Якщо потрібно показати 20 записів, які знаходяться на третій сторінці з прикладу вище, то слід скористатися наступним кодом:

$args = array(
‘posts_per_archive_page’ => ’20’,
‘paged’ => ‘3’
);

Також можна використовувати аргумент offset:

$args = array(
‘posts_per_page’ => ’20’,
‘offset’ => ’40’
);

Цей запит пропустить 40 записів, які розташовані на перших двох сторінках архіву, і отримає наступні 20 (з третьої сторінки).

Також можна повністю відключити пагінацію, і тоді всі записи будуть відображені на одній сторінці:

$args = array(
‘nopaging’ => true
);

На завершення

Клас WP_Query є досить гнучким з точки зору визначення кількості записів запиту, їх сортування і статусу.

Деякі аргументи зручно використовувати в запитах до певних типів записів. Наприклад, аргумент ‘post_status’ => ‘inherited’ при роботі з вкладеннями. А з допомогою інших можна контролювати виконання самих запитів.

Переклад статті «WP_Query Arguments: Status, Order and Pagination» був підготовлений дружною командою проекту Сайтостроение від А до Я.

ЭТО МОЖЕТ БЫТЬ ИНТЕРЕСНОЕЩЕ ОТ АВТОРА