WP-API JavaScript клиент (Backbone.js)

В REST API есть JavaScript клиент, который позволяет удобно общаться с сайтом. Библиотека содержит Модели и Коллекции на все конечные точки WP, описанные в разделе Маршруты WP из коробки, а также на все эндпоинты, созданные вручную.

Использование

Чтобы включить библиотеку WP API нужно подключить скрипт wp-api.

Сделать это можно напрямую:

wp_enqueue_script( 'wp-api' );

или через зависимость от нашего скрипта, например, my_script:

wp_enqueue_script( 'my_script', 'path/to/my/script', array('wp-api') );

Библиотека анализирует корневую конечную точку (схему REST API) и создает по ней Backbone модели и коллекции. Таким образом у нас появляется два основных объекта: wp.api.models и wp.api.collections, которые содержат следующие JS методы:

// Модели:
wp.api.models.Category
wp.api.models.Comment
wp.api.models.Media
wp.api.models.Page
wp.api.models.PageMeta
wp.api.models.PageRevision
wp.api.models.Post
wp.api.models.PostMeta
wp.api.models.PostRevision
wp.api.models.Schema
wp.api.models.Status
wp.api.models.Tag
wp.api.models.Taxonomy
wp.api.models.Type
wp.api.models.User

// Коллекции:
wp.api.collections.Categories
wp.api.collections.Comments
wp.api.collections.Media
wp.api.collections.PageMeta
wp.api.collections.PageRevisions
wp.api.collections.Pages
wp.api.collections.Posts
wp.api.collections.Statuses
wp.api.collections.Tags
wp.api.collections.Taxonomies
wp.api.collections.Types
wp.api.collections.Users

Мы можем использовать эти объекты (конечные точки) для чтения/обновления/создания/удаления элементов с помощью стандартных методов (fetch, sync, save и destroy для models, sync для collections).

Значения по умолчанию

Каждая Модель и Коллекция содержит ссылку на значения по умолчанию, например:

wp.api.models.Post.prototype.args

author         : null
comment_status : null
content        : null
date           : null
date_gmt       : null
excerpt        : null
featured_image : null
format         : null
modified       : null
modified_gmt   : null
password       : null
ping_status    : null
slug           : null
status         : null
sticky         : null
title          : null

Доступные методы

Каждая Модель и Коллекция содержит список методов, которые поддерживает соответствующая конечная точка. Например, модель wp.api.models.Post имеет следующие методы:

["GET", "POST", "PUT", "PATCH", "DELETE"]

Принимаемые параметры

Каждая Модель и Коллекция содержит список параметров, которые принимает соответствующая конечная точка (обратите внимание, что параметры передаются в качестве второго аргумента при создании моделей или коллекций), например:

wp.api.collections.Posts.prototype.options

// содержит:
author
context
filter
order
orderby
page
per_page
search
status

Примеры использования Моделей

Чтобы создать/изменить запись (пост), убедитесь, что вы авторизованы и у вас есть достаточные для этого права.

// Создаем новый пост
var post = new wp.api.models.Post( { title: 'Это пробный пост' } );
post.save();

Пример работы с записью (постом):

// Получим пост ID=1
var post = new wp.api.models.Post( { id: 1 } );
post.fetch();

// Получим коллекцию категорий поста (вернет promise).
// Использует _embedded данные (если можно), в этом случае promise срабатывает немедленно.
post.getCategories().done( function( postCategories ) {
	// ... делаем что-нибудь с рубриками
	// у нового поста есть всего одна рубрика: Uncategorized
	console.log( postCategories[0].name ); // выведет "Uncategorized"
} );

// Получим автора поста (User модель)
post.getAuthorUser().done( function( user ){
	// ... делаем что-нибудь с юзерами
	console.log( user.get( "name" ) );
} );

// Получим картинку поста (Media модель).
post.getFeaturedMedia().done( function( image ){
	// ... делаем что-нибудь с картинкой
	console.log( image );
} );

// Установим рубрики поста
post.setCategories( [ "apples", "oranges" ] );

Пример работы с рубриками:

// Получим все рубрики
var allCategories = new wp.api.collections.Categories()
allCategories.fetch();

// Найдем рубрику apples
var appleCategory = allCategories.findWhere( { slug: "apples" } );

// Добавим полученный выше пост в рубрику "apples" (установим рубрику для поста)
appleCategory.set( "parent_post", post.get( "id" ) );

Примеры использования Коллекций

Получим 10 последних постов:

var postsCollection = new wp.api.collections.Posts();
postsCollection.fetch();

Получим 25 последних постов:

postsCollection.fetch( { data: { per_page: 25 } } );

Используем фильтр, чтобы изменить параметры сортировки (order и orderby):

postsCollection.fetch( { data: { 'filter': { 'orderby': 'title', 'order': 'ASC' } } } );

Все коллекции поддерживают пагинацию автоматически, и следующий пакет результатов можно получить с помощью метода more():

postsCollection.more();

Получим страницу 5 из коллекции:

posts.fetch( { data: { page: 5 } } );

Проверим есть ли в коллекции еще записи (посты):

posts.hasMore();

Ожидание загрузки wp-api клиента (скрипта)

Backbone.js загружается асинхронно. Если схема api локализована и не нужно делать AJAX запрос на получение схемы, то клиент начинает работу сразу же. Однако когда нужно подождать полную готовность клиента к работе, нужно использовать loadPromise.done:

wp.api.loadPromise.done( function() {
	// Тут можно использовать клиент
} )

Работа с ревизиями

Через коллекции PostRevisions или PageRevisions, можно получить все ревизии постов/страниц. Или ревизии можно получить из коллекций Post или Page.

Например, получим все ревизии поста 1:

var revisions = new wp.api.collections.PostRevisions({}, { parent: 1 });

Коллекции редакций также могут быть доступны через родительскую коллекцию. В этом примере выполняется 2 HTTP-запроса вместо одного, но теперь доступна исходная запись и ее редакции:

var post = new wp.api.models.Post( { id: 1 } );
post.fetch();
post.getRevisions().done( function( revisions ){
  console.log( revisions );
});

Если были добавлены свои конечные точки в API, то они также становятся доступными как модели/коллекции. Например, вы получите новые модели и коллекции при добавлении поддержки rest API в пользовательский Тип записи.