Skip to content
This repository has been archived by the owner on Oct 6, 2024. It is now read-only.

magicink/use-wordpress

Repository files navigation

Build Status

Overview

Useful React Hooks for WordPress.

Installation

npm i -D use-wordpress

Requirements

This library relies upon an implementation of WHATWG fetch and URLSearchParams.

Initialization

useWordPress(nonce: string, baseUri: string)

Usage

import React from 'react'
import { useWordPress } from 'use-wordpress'
export const TestComponent = props => {
  const { data, get, total, totalPages } = useWordPress(wpApiSettings.nonce)
  const [initialized, setInitialized] = React.useState(false)
  React.useEffect(() => {
    if (!initialized) {
      get('categories') // Fetches categories and assigns them to data
      setInitialized(true) 
    }
  }, [])
  return (
    // ...
  )
}

Arguments

name type required default description
nonce string yes A "number used once" to help protect URLs and forms from certain types of misuse. Learn more about nonces.
baseUri string no ?/rest_route=/wp/v2 The base URI of WordPress's REST API.

API

Properties

name type description
data any The response from the fetch call.
embedded Object Stores the _embedded property of an entity if it exists.
featuredMedia Array<Object> Stores the wp:featuredmedia array of embedded if it exists.
error Error Any errors returned from the fetch calls.
loading boolean Whether or not a fetch is currently being performed.
total Number The total number of records in the collection.
totalPages Number the total number of pages encompassing all available records.

Methods

fetchData (endpoint: string, callback: Function, headers: Object)

A wrapper for window.fetch(). Populates total and totalPages with the values of x-wp-total and x-wp-totalpages, respectively, if they are present in the response header.

name type required default description
endpoint string yes The portion of the URI that is appended on the base URI passed into the initializer.
callback Function yes A callback that invoked upon a successful fetch request.
headers Object no Headers passed to the fetch call.

get (type: string, options: {[key: string]: string}, getEmbedded: boolean)

Used to fetch a collection of type.

name type required default description
type string no posts The type of record your are fetch (i.e posts, pages, categories).
options SearchParams no {} An object that is converted into search parameters.
getEmbedded boolean no false If true it will add the _embed search parameter to the fetch.

getById (id: number, type: string, options: {[key: string]: string, getEmbedded: boolean)

Used to fetch a record by its ID.

name type required default description
id number yes The ID of the record your are trying to fetch.
type string yes posts The type of record your are fetch (i.e posts, pages, categories).
options SearchParams no {} An object that is converted into search parameters.
getEmbedded boolean no false If true it will add the _embed search parameter to the fetch.

getBySlug (slug: string, type: string, options: {[key: string]: string, getEmbedded: boolean)

Used to fetch a record by its slug.

name type required default description
slug string yes The slug of the record your are trying to fetch.
type string yes posts The type of record your are fetch (i.e posts, pages, categories).
options SearchParams no {} An object that is converted into search parameters.
getEmbedded boolean no false If true it will add the _embed search parameter to the fetch.

getEmbedded (entity: {'_embedded': Object})

Stores the _embedded of entity if it exists. The value of _embedded is assigned to embedded (see "Properties").

name type required default description
entity {'_embedded': Object} yes The data source.

getFeaturedMedia (embedded: {'wp:featuredmedia': Array<Object>})

Stores the wp:featuredmedia of embedded if it exists. The value of wp:featuredmedia is stored in featuredMedia (see "Properties").

name type required default description
embedded {'wp:featuredmedia': Array<Object>} yes The data source.

getPageById (id: number, options: Object, getEmbedded: boolean)

A wrapper for getById used to get a page by its ID.

name type required default description
id number yes The ID of the page.
options SearchParams no {} An object that is converted into the request search params.
getEmbedded boolean no true If true the request will also fetch embedded objects.

getPageBySlug (slug: string, options: Object, getEmbedded: boolean)

A wrapper for getBySlug used to get a page by its slug.

name type required default description
slug string yes The slug of the page.
options SearchParams no {} An object that is converted into the request search params.
getEmbedded boolean no true If true the request will also fetch embedded objects.

Data Types

SearchParams: {[key: string]: string}