Время для прочтения: 2 мин. 30 сек.

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

WordPress REST API "из коробки" включает в себя клиентскую JavaScript-библиотеку на основе фреймворка Backbone.js.

Бибилотека предоставляет интерфейс к WP REST API, используя модели и коллекции Backbone для всех конечных точек (эндпоинтов) в схеме 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.

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

Ссылки

Пошерить
Плюсануть
Отправить
Вотсапнуть

Добавить комментарий

Такой e-mail уже зарегистрирован. Воспользуйтесь формой входа или введите другой.

Вы ввели некорректные логин или пароль

Извините, для комментирования необходимо войти.

1. Нажимая на кнопку "Отправить", я даю согласие на обработку персональных данных.

2. Для вставки кода используйте специальные теги [code lang="php"]ваш код[/code]