https://github.com/magicink/use-wordpress

Useful React Hooks for WordPress
https://github.com/magicink/use-wordpress

hooks react wordpress

Last synced: 16 days ago
JSON representation

Useful React Hooks for WordPress

• Host: GitHub
• URL: https://github.com/magicink/use-wordpress
• Owner: magicink
• Created: 2019-08-17T17:45:45.000Z (over 5 years ago)
• Default Branch: develop
• Last Pushed: 2023-07-09T18:05:03.000Z (over 1 year ago)
• Last Synced: 2024-03-02T10:07:13.273Z (10 months ago)
• Topics: hooks, react, wordpress
• Language: JavaScript
• Homepage:
• Size: 359 KB
• Stars: 2
• Watchers: 1
• Forks: 0
• Open Issues: 5
• Metadata Files:
  • Readme: README.md

Awesome Lists containing this project

README

        
[![Build Status](https://travis-ci.org/magicink/use-wordpress.svg?branch=develop)](https://travis-ci.org/magicink/use-wordpress)

# 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

```js

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](https://developer.wordpress.org/rest-api/using-the-rest-api/authentication/). |

| `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` | 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})`

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}` | 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}`