Source API
State
Let’s start by explaining how the state data is used and then how that data is requested and stored. The state works with two main concepts: paths and entities.
The state is designed so that you can know which entities correspond to which path, and then access the data of these entities in a simple way.
NOTE: for the data to exist, it will be necessary to request them previously using the fetch action.
example
// Accessing path's data
const data = source.data["/categories/nature"]
// `data` value:
({
// Type & id of the entity
type: "category",
id: 2,
// Type & id of the listed entities
// (when the path is an archive or similar)
items: [{ type: 'post', id: 60, path }, ...], // all fetched entities
pages: [[{ type: 'post', id: 60, path }, ...]], // fetched entities per page
totalItems: // total number of entities
totalPages: // total number of pages
// Booleans to easily identify the type of path
// inside the WP hierarchy
isArchive: true,
isTaxonomy: true,
isCategory: true,
})
// Accessing the entity's properties
const entity = source[d.type][d.id]
// `entity` value:
({
id: 2,
count: 23,
description: "Beautiful nature locations",
link: "https://myblog.com/category/nature/",
name: "Nature",
slug: "nature",
taxonomy: "category",
})
The information to distinguish each type of path is based on the WP Template Hierarchy and is as follows:
- archives:
isArchive
- taxonomy:
isTaxonomy (with type, id properties)
- category:
isCategory
- tag:
isTag
- deal:
isDeal
- author:
isAuthor (with id property)
- postTypeArchive:
isPostTypeArchive (with type property)
- post:
isHome, isPostArchive (isFrontPage optional)
- product:
isProductArchive
- date:
isDate (with date)
- postTypes:
isPostType (with type, id properties)
- post:
isPost
- page:
isPage (isFrontPage optional)
- product:
isProduct
- media:
isMedia, isAttachment
- 404:
is404
State API
source.data[path]
Access data related to a path. The path parameter could be also a name that identifies custom lists. See source.add for more info.
source.data["/the-beauties-of-gullfoss"]
source.data["/category/nature"]
source.data["gallery-post-60"]
source.taxonomy[taxonomy]
Access taxonomy entities. taxonomy can be "category", "tag" or any custom taxonomy slug. That value is stored in the type attribute of the source.data[path] object.
source.taxonomy["category"]
source.taxonomy["tag"]
source.taxonomy["deal"] // custom taxonomy
source[taxonomy][id]
Access category, tag, or custom taxonomy’s entities.
source.category[2]
source.tag[13]
source.deal[3]
source.type[type]
Access post types. type can be "post", "page", "attachment" or any custom post type.
source.type["post"]
source.type["page"]
source.type["product"] // custom post type
source[type][id]
Access posts, pages, attachments or custom post type’s entities.
source.post[60]
source.page[7]
source.product[36]
source.author[id]
Access author entities.
source.author[4]
Actions
source.fetch(path, page)
Action that retrieves entities using a path or a name. fetch works using the corresponding fetch function defined with the add action. This action doesn’t return anything but ensures that the received data are correctly populated in the state.
arguments
-
path: string that contains a path or a custom list’s name
-
page: page number (default is 1)
example
source.fetch("/category/nature")
source.fetch("/category/nature", 2)
source.fetch("/the-beauties-of-gullfoss")
source.fetch("custom-list")
There are some URL patterns handled by default. Those are:
postArchive: '/(?s=:search)'
category: '/category/:slug(/?s=:search)'
tag: '/tag/:slug(/?s=:search)'
author: '/author/:name(?=:search)'
date: '/:year/:month?/:day?(?s=:search)'
postOrPage: '/:slug'
attachment: '/:year/:postSlug/:attachmentSlug'
source.add(pattern, callback)
Action that attaches a function to handle a specified name or route pattern, using a string or a regexp. That function should request data from the WP REST API and populate the store with it. For that purpose, you may use the populate action.
arguments
example
source.add(
"/post/:slug",
async ({ state, actions, effects }, { name, params }) => {
// Get a post
const { body: post } = await effects.api.get(
{
endpoint: "/wp/v2/posts",
params: {
slug: params.slug
}
}
);
// Populate data response in the store
actions.source.populate(name, post);
}
)
source.populate(path, entities, page)
Action that stores entities in the state so you can find them using the API specified in the State API section. Also, it sets all info related to paths for each entity (based on the entity’s link). This action is intended to be used after request entities from the REST API (using api.get effect).
arguments
-
path: path or name
-
entities: array or a single entity, from a WP REST API request
-
page: the requested page number
example
source.populate('/category/nature', posts, 1)
// That action should populate all the state below
source.data['/category/nature']
source.data["/categories/nature"].page[1]
source.data["/categories/nature"].items
source.category[2]
source.data['/the-beauties-of-gullfoss']
source.post[60]
source.data["/author/luis"]
source.author[4]
source.attachment[15]
source.attachment[16]
NOTE: when using a name instead of a path, any property to identify that name should be added explicitly:
source.populate("gallery-1", attachments, 1)
// That action should populate all the state below
source.data["gallery-1"]
source.data["gallery-1"].page[1]
source.data["gallery-1"].items
source.attachment[15]
source.attachment[16]
// ...
// This should be added explicitly
source.data["gallery-1"].isGallery = true
Effects
api.get({ endpoint, params })
Request entity to the WordPress REST API.
arguments
-
endpoint: name of the endpoint if is a /wp/v2 endpoint (e.g. posts), or the full path of other REST endpoints (e.g. /frontity/v1/discovery)
-
params: any parameter that will be included in the query params.
For more info, visit the WP REST API reference.
example
// Get posts from categories 2, 3 and 4
api.get({ endpoint: "posts", params: { _embed: true, categories: '2,3,4' } });
// Get the page 14
api.get({ endpoint: "pages", params: { _embed: true, include: '14' } });
// Other endpoints:
api.get({
endpoint: "/frontity/v1/discovery",
params: { path: "/the-beauties-of-gullfoss" }
});
Settings
All the options that can be configured in the package settings, like if it is WordPress.org or WordPress.com, the REST base route, etc.
