wp-source
package to your project:@frontity/mars-theme
& @frontity/twentytwenty-theme
) available when doing npx frontity create
already include this wp-source
package.frontity.settings.js
file as one of the packages that will be part of the Frontity project:frontity.settings.js
file:state.source.url
state.frontity.url
.state.frontity.url
property is set, you do not have to also set the state.source.url
property as this will be the same as the value in the state.frontity.url
property.state.source.api
@frontity/wp-source
package, the property state.source.api
should never be set manually by the end-users (it will be computed from properties like state.source.url
or state.wpSource.isWpCom
).state.source.api
for every WordPress scenario.state.wpSource.isWpCom
false
by default and will be automatically computed to true
if needed in most of the cases.true
if you're using a Personal or Premium WordPress.com plan.state.wpSource.prefix
"/wp-json"
or "?rest_route=/"
. The default value is "/wp-json"
.state.source.subdirectory
blog
or /blog
. It also transform links of the entities that come from the REST API.state.source.homepage
/about-us
then that page will be shown if you access /
./
route, you should set state.source.postsPage
as well in order to be able to access the posts archive in a different route.state.source.postsPage
/blog
, then the posts archive will be shown if you access /blog
instead of /
. It is useful when used in combination with state.source.homepage
.state.source.categoryBase
state.source.tagBase
state.source.postEndpoint
"posts"
.state.source.params
actions.source.fetch
. This is useful to filter fields from the REST API, change the default per_page
value and so on. For example, if you set this value toactions.source.fetch
), the query part of the HTTP call to the REST API will be per_page=5&type[]=post&type[]=page
.state.source.auth
state.source.auth
in a variety ways, e.g. via frontity.settings.js
or by setting it in the way that any other piece of frontity state is.state.source.auth
can be set via a query string. If a frontity_source_auth
Frontity Query Option param is present in the URL state.source.auth
will use its value. Values passed in this way will be removed from the initialLink
URL and added to state.frontity.options
.Note that the Frontity Query Option parameters are camelCased when they are added tostate.frontity.options
, so thefrontity_source_auth
query string param will becomestate.frontity.options.sourceAuth
once added.
state.source.auth
can also be set from an environmental variable. If frontity detects a FRONTITY_SOURCE_AUTH
environmental variable, it will pass its value to state.source.auth
.Note that the value passed from the URL query string takes precedence over the value from the env variable.Frontity loads environmental variables from .env files using the https://github.com/motdotla/dotenv/ package.
state.source.auth
is removed in the afterSSR()
action, so if state.source.auth
is present in the state on the server its value will not be sent to the client, thus confidential credentials are not revealed client-side.state.source.redirections
wp-source
package, Frontity has support for 3xx Redirections that are stored in the WordPress database. Such redirections can be added for example via the popular Redirection plugin.state.source.redirections
we can configure how we want to handle the redirections. This property can have one of the following values:"no"
- Does not handle the redirections at all. This is the default."404"
- Only send the additional request to the WordPress instance if the original request has returned a 404 error."all"
- Always make an additional request to the WordPress instance to check if there exists a redirection. This means that for every single actions.source.fetch()
there will be a parallel request to the WordPress server that is fired "just in case" the actions.source.fetch()
returns a 404. If the actions.source.fetch()
is successful, the result of fetching the redirection is discarded. If actions.source.fetch()
fails, Fronity waits for the response from fetching the redirection and if that is successful, uses its result.string
- A string that contains a regex pattern. The string must start with "RegExp:"
. This pattern will be matched against the current route and if matched, Frontity will make an additional request to the WordPress instance to check if there exists a redirection. Note that the shorthand character classes will have to be escaped, so for example instead of \d
, you will need to write \\d
.string[]
- An array of strings, which can contain the "404"
value as well as any number of strings starting with "RegExp:/"
which represent regular expressions. An additional request will be sent to Wordpress to check for the redirection if any of the regular expressions match the current route. If the array also contains a "404"
, an additional request will also be made if the original request has returned a 404 error."no"
"all"
"404"
"RegExp:/some-post/(\\d*)"
"RegExp:/post-(\\w*)/(\\d*)"
["404", "RegExp:/some-post/", "RegExp:/another-post"]
state.source.postTypes
type
endpoint
archive
type
and endpoint
may be confusing as they are usually the same. You can confirm you are doing it correctly going to the CPT endpoint
:state.source.taxonomies
postTypes
setting, this one allows you to show the lists of posts of a Custom Taxonomies you create at WordPress when accessing their URLs. It is an array of objects, each object being a different Custom Taxonomy. It has four arguments:taxonomy
endpoint
postTypeEndpoint
posts
params
taxonomy
and endpoint
may be confusing as they usually are the same too. You can confirm you are doing it correctly by going to the Custom Taxonomy endpoint
:taxonomy
and endpoint
are different. In the next example, we will fetch CPT "movies" instead of "posts", and add some params. It would be something like this:@frontity/wp-source
package requires pretty permalinks to be enabled on the WordPress admin. For more info check the guide WordPress requirements for Frontity.fetch
action.wp-source
package, here you have some videos where the Frontity DevRel team talks about it:wp-source
package implements the interface defined in the source
package and adds some extra API.actions.source.fetch()
link
, i.e. the pathname of a URL in your site.state.source.data
with information about that link.state.source.post
, state.source.category
or state.source.author
and so on.link
options
options
.force
Promise
state.source
and are accessible using the methods explained in the next section.async/await
with fetch
because:state
accessed changes.fetch
is called again for the same link
it does nothing, as all the entities have already been fetched and there is no need to request them again. If you do want to fetch them again, you can pass an options object to source.fetch
with force: true
:actions.source.fetch()
is recommended over other isomorphic methods to fetch data such as axios
or superagent
, because:actions.source.fetch()
is also recommended over window.fetch
because although window.fetch
exists in the browser it is not isomorphic and doesn't exist in Node.actions.router.set
for example) a new fetch should be done for that new link so the data of that link is properly populated to the state.state.router.autoFetch
with a default value of true, every time you browse to a new page (Client Side Navigation) the fetch of the data in that page will we done automatically for you.state.source.get()
link
isArchive
isTaxonomy
isCategory
isTag
isDeal
isAuthor
isPostTypeArchive
isHome
, isPostArchive
(isFrontPage
optional)isProductArchive
isDate
isPostType
isPost
isPage
(isFrontPage
optional)isProduct
isMedia
, isAttachment
is404
get()
has returned a status code higher than 400
, we add information about the error to the state. For example, if an error code was 500
, the state will include the following properties:taxonomy
, id
id
type
year
, month
, date
type
, id
state.source[taxonomy][id]
taxonomy
value from post_tag
to tag
.state.source[type][id]
state.source.author[id]
libraries.source.api.get()
options
options
.endpoint
/wp/v2
endpoint (e.g. posts
), or the full path of other REST endpoints (e.g. /acf/v3/posts
).options
.params
options
.auth
state.source.auth
if that value is present in the state.options
.api
api.set.
options
.isWpCom
api.set.
Promise
libraries.source.populate()
options
options
.response
api.get().
options
.state
options
.subdirectory
state.source.subdirectory
options
.force
false
Array
type
, id
and link
representing the added entities.populate
should be called with force: true
.libraries.source.handlers
handlers
are used when actions.source.fetch
is called.name
priority
fetch
to know in which order handlers should be evaluated.pattern
pattern: "RegExp:foo(?!bar)"
func
func
property defined will receive an object with the following propertieslink
params
state
libraries
force
actions.source.fetch
call.Promise
libraries.source.handlers
is an array., so to add new handlers we can use libraries.source.handlers.push()
libraries.source.redirections
redirections
are used when actions.source.fetch
is executed, before handlers
.name
priority
fetch
to know in which order redirections should be evaluated.pattern
func
func
property defined will receive an object with the following propertiesslug
libraries.source.parse()
link
resultParse
resultParse
.path