Backbone JavaScript-клиент для WordPress REST API

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

Тут варианта всего два: либо напрямую подключить wp-api:

wp_enqueue_script( 'wp-api' );

Либо поставить данный скрипт в зависимости к любому из своих внутри темы или плагина:

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

Библиотека парсит корневые эндпоинты и создаёт соотношения Backbone-моделей и коллекций. После чего вам становятся доступными два корневых объекта: wp.api.models и wp.api.collections.

Модели включают в себя:

• Category
• Comment
• Media
• Page
• PageMeta
• PageRevision
• Post
• PostMeta
• PostRevision
• Schema
• Status
• Tag
• Taxonomy
• Type
• User

Коллекции включают в себя:

• Categories
• Comments
• Media
• PageMeta
• PageRevisions
• Pages
• Posts
• Statuses
• Tags
• Taxonomies
• Types
• Users

Используя эти эндпоинты, как есть, вы можете читать, обновлять, создавать и удалять записи, причём работает это всё на стандартных методах Backbone (fetch, sync, save и destroy для моделей, sync для коллекций). Эти объекты очень просто расширяются, благодаря чему вы с легкостью можете построить свои представления поверх них.

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

Каждая модель или представление включают в себя ссылку на значения по умолчанию. Например, для 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

Обратите внимание, что параметры передаются вторым аргументом при создании моделей или коллекций.

Локализация схемы API

Клиент получает и использует cхему как часть объекта wpApiSettings.

В настоящее время схема не передается по умолчанию, вместо этого клиент делает ajax-запрос к API для загрузки cтруктуры, а затем кэширует его в сессионом хранилище браузера (если доступно).

Смотрите пример client-js или эту ветку в репозитории, которая пытается локализовать схему только один раз на каждого клиента.

При включенном SCRIPT_DEBUG плагин client-js начинает использовать локализованную схему.

Ждём загрузку клиента

Клиент стартует асинхронно. Если схема API локализована — клиент стартует немедленно, если нет — клиент делает ajax-запрос для загрузки схемы. Вся магия заключена в промисах (promise):

wp.api.loadPromise.done( function() {
	// тут ваш код
} );

Примеры моделей

Перед созданием поста или редактированием категорий убедитесь, что вы залогинены, а затем:

// Создать новый пост
var post = new wp.api.models.Post( { 
	title: 'Это тестовая публикация' 
} );
post.save();
 
// Загрузить существующий пост
var post = new wp.api.models.Post( { 
	id: 1 
} );
post.fetch();
 
// Получить коллекцию категорий поста (вернется промис)
// Используется _embedded данные, если доступны
post.getCategories().done( function( postCategories ) {
	// ... делаем что-либо с категориями.
	// Новый пост имеет всего одну категорию
	// под названием "Без категории"
	console.log( postCategories[0].name );
	// response -> "Без категории"
} );
 
// Получить автора поста
post.getAuthorUser().done( function( user ){
	// ... делаем что-нибудь с юзером
	console.log( user.get( 'name' ) );
} );
 
// Получить "тумбочку" поста
	post.getFeaturedImage().done( function( image ){
	// ... делаем что-либо с фото
	console.log( image );
} );
 
// Установить категории поста
post.setCategories( [ 'ананы', 'бананасы' ] );
 
// Получить все категории сайта
var allCategories = new wp.api.collections.Categories()
allCategories.fetch();

// Найти категорию по слюгу
var appleCategory = allCategories.findWhere( { slug: 'anany' } );
 
// Добавить категорию к коллекции postCategories, что получены выше
appleCategory.set( 'parent_post', post.get( 'id' ) );
 
// Заюзать метод POST
postCategories.create( appleCategory.toJSON(), { type: 'POST' } );
 
// Удалить категорию "Без категории"
postCategories.at( 0 ).destroy();
 
// Проверить результат и 
// при необходимости повторить
postCategories = post.getCategories();
 
postCategories.at( 0 ).get( 'name' );
// response -> "ананы"

Примеры коллекций

// Получить последние 10 постов
var postsCollection = new wp.api.collections.Posts();
postsCollection.fetch();

// Получить последние 25 постов
postsCollection.fetch( { 
	data: { 
		per_page: 25 
	} 
} );

// Изменить сортировку при помощи фильтра

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

// Пагинация для всех коллекций добавляется автоматом,
// поэтому можно получить следующую страницу при помощи more()
postsCollection.more();

// Получить пятую страницу коллекции
posts.fetch( { data: { page: 5 } } );

// Проверить, что коллекия имеет
// следующую страницу
posts.hasMore();

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

Ддя доступа к ревизиям поста или страницы есть специальные коллекции PostRevisions или PageRevisions.

// Получить все ревизии пост с ID=1
var revisions = new wp.api.collections.PostRevisions({}, { 
	parent: 1 
} );

// Коллекции ревизии также можно получить 
// из родительских коллекций самого поста.
// Но это займет два HTTP-запроса, зато у вас будет
// доступ к оригинальному посту и его коллекциям
var post = new wp.api.models.Post( { id: 1 } );
post.fetch();
post.getRevisions().done( function( revisions ) {
	console.log( revisions );
});

Если вы добавляет кастомные эндпоинты в API, то они также становятся доступным в качестве моделей и коллекций. Например, вы получите рабочие модели и коллекции, если при регистрации поста через register_post_type() или при регистрации таксономии через register_taxonomy(), если вы добавите ключ массива 'show_in_rest' => true.

Поскольку схема сохраняется в сессионном кеше пользователя, вы можете повторить запрос даже в новой вкладке браузера без создания дополнительных запросов на сервер.

Ссылки

• Backbone WP-API + REST API and model view updates
• Writing your first application using Backbone.js
• Backbone JavaScript Client