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
.
Поскольку схема сохраняется в сессионном кеше пользователя, вы можете повторить запрос даже в новой вкладке браузера без создания дополнительных запросов на сервер.
Ссылки
- Backbone WP-API + REST API and model view updates
- Writing your first application using Backbone.js
- Backbone JavaScript Client
А можно конкретный пример работы с CPT? То есть вот это же
// Создать новый пост
var
post =
new
wp.api.models.Post( {
title:
'Это тестовая публикация'
} );
post.save();
но для CPT (поддержка Rest API у него включена, все ок). Post Type Slug * = reviews, Plural Label = Reviews, Singular Label = Review, REST API base slug = Review, REST API controller class = (default)
Замените Post на имя вашего CPT.