Skip to content

Commit 4f3bae0

Browse files
author
Maurice Snip
committed
docs: add readme
1 parent bfb8c0d commit 4f3bae0

File tree

1 file changed

+205
-0
lines changed

1 file changed

+205
-0
lines changed

‎README.md‎

Lines changed: 205 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,205 @@
1+
# Sulu Headless API Client
2+
3+
This module provides a [`Promise`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) based way to work with the [`SuluHeadlessBundle`](https://github.com/sulu/SuluHeadlessBundle) JSON API.
4+
5+
<p>
6+
<img src="https://img.shields.io/badge/npm-v1.0.0-blue">
7+
<img src="https://img.shields.io/badge/license-MIT-green">
8+
</p>
9+
10+
## Installation
11+
12+
```sh
13+
# With npm
14+
npm install sulu-headless-api-client
15+
16+
# Or yarn
17+
yarn add sulu-headless-api-client
18+
```
19+
20+
## Basic usage
21+
22+
```javascript
23+
import Client from 'sulu-headless-api-client';
24+
25+
// Create client
26+
const client = new Client();
27+
28+
// Get page data
29+
client
30+
.getPageByPath(window.location.pathname)
31+
.then((page) => {
32+
// Do something with page data...
33+
});
34+
```
35+
36+
## Advanced usage
37+
38+
```javascript
39+
import Client from 'sulu-headless-api-client';
40+
import sortNavigation from './helpers/sortNavigation';
41+
42+
// Create client
43+
const navigationClient = new Client({
44+
baseUrl: process.env.SULU_BASE_URL,
45+
removeEmbedded: true,
46+
onResponse: (response) => sortNavigation(response),
47+
});
48+
49+
// Get navigation data
50+
navigationClient
51+
.getNavigationByKey('main', {
52+
depth: 3,
53+
excerpt: true,
54+
flat: true,
55+
})
56+
.then((navigation) => {
57+
// Do something with navigation data...
58+
});
59+
```
60+
61+
Or with [Axios](https://axios-http.com/).
62+
63+
```javascript
64+
import Client from 'sulu-headless-api-client';
65+
import axios from 'axios';
66+
import sortNavigation from './helpers/sortNavigation';
67+
68+
// Create client
69+
const navigationClient = new Client({
70+
baseUrl: process.env.SULU_BASE_URL,
71+
fetchClient: axios,
72+
fetchOptions: {
73+
transformResponse: (response) => sortNavigation(response),
74+
},
75+
removeEmbedded: true,
76+
});
77+
78+
// Get navigation data
79+
navigationClient
80+
.getNavigationByKey('main', {
81+
depth: 3,
82+
excerpt: true,
83+
flat: true,
84+
})
85+
.then((navigation) => {
86+
// Do something with navigation data...
87+
});
88+
```
89+
90+
## Error handling
91+
92+
```javascript
93+
import Client from 'sulu-headless-api-client';
94+
import handleError from './helpers/handleError';
95+
import handleSearchError from './helpers/handleSearchError';
96+
97+
// Client wide
98+
const client = new Client({
99+
onError: (error) => handleError(error),
100+
});
101+
102+
// Or per method
103+
client
104+
.getPageByPath(window.location.pathname)
105+
.then((page) => {
106+
// Do something with page data...
107+
})
108+
.catch((error) => handleError(error));
109+
110+
client
111+
.search(query)
112+
.then((hits) => {
113+
// Do something with hits...
114+
})
115+
.catch((error) => handleSearchError(error));
116+
```
117+
118+
## Constructor
119+
120+
### `const client = new Client(options)`
121+
122+
Creates a client.
123+
124+
#### Parameters
125+
126+
| Parameter | Required? | Type | Default | Description |
127+
|:-------------------------|:----------|:--------------------|:---------------------------|:----------------------------------------------------------------------|
128+
| `options` | No | `Object` | `{}` | The options for the client. |
129+
| `options.baseUrl` | No | `string` | `window.location.pathname` | The base URL for the API. |
130+
| `options.fetchClient` | No | `Function` | `fetch` | The fetch client to use. Tested with `fetch` and `axios`. |
131+
| `options.fetchOptions` | No | `Object` | `{}` | The fetch client options. |
132+
| `options.onError` | No | `Function(error)` | `() => {}` | The function to call on error. |
133+
| `options.onResponse` | No | `Function(reponse)` | `(r) => r` | The function to call on response. |
134+
| `options.removeEmbedded` | No | `boolean` | `false` | Whether to remove the `_embedded` layer from the response if present. |
135+
136+
## Instance methods
137+
138+
### `client.getPageByPath(path)`
139+
140+
Retrieves page data from the given path.
141+
142+
#### Parameters
143+
144+
| Parameter | Required? | Type | Default | Description |
145+
|:----------|:----------|:---------|:--------|:----------------------------------|
146+
| `path` | Yes | `string` | - | The path of the page to retrieve. |
147+
148+
#### Return value
149+
150+
A `Promise` that resolves to the page data.
151+
152+
### `client.getNavigationByKey(key[, params])`
153+
154+
Retrieves navigation data with the given key and optional query parameters.
155+
156+
#### Parameters
157+
158+
| Parameter | Required? | Type | Default | Description |
159+
|:-----------------|:----------|:----------|:--------|:-------------------------------------------|
160+
| `key` | Yes | `string` | - | The key of the navigation to retrieve. |
161+
| `params` | No | `Object` | `{}` | The query parameters for the request. |
162+
| `params.depth` | No | `number` | `1` | The maximum depth of the navigation. |
163+
| `params.excerpt` | No | `boolean` | `false` | Whether to include excerpt data. |
164+
| `params.flat` | No | `boolean` | `false` | Whether to return as list instead of tree. |
165+
166+
#### Return value
167+
168+
A `Promise` that resolves to the navigation data.
169+
170+
### `client.getSnippetByArea(area[, params])`
171+
172+
Retrieves snippet data with the given area name and optional query parameters.
173+
174+
#### Parameters
175+
176+
| Parameter | Required? | Type | Default | Description |
177+
|:--------------------------|:----------|:----------|:--------|:------------------------------------------|
178+
| `area` | Yes | `string` | - | The name of the snippet area to retrieve. |
179+
| `params` | No | `Object` | `{}` | The query parameters for the request. |
180+
| `params.includeExtension` | No | `boolean` | `false` | Whether to include extension data. |
181+
182+
#### Return value
183+
184+
A `Promise` that resolves to the snippet area data.
185+
186+
### `client.search(query)`
187+
188+
Performs a search with the given query.
189+
190+
#### Parameters
191+
192+
| Parameter | Required? | Type | Default | Description |
193+
|:----------|:----------|:---------|:--------|:------------------|
194+
| `query` | Yes | `string` | - | The search query. |
195+
196+
#### Return value
197+
198+
A `Promise` that resolves to the search results.
199+
200+
## Testing
201+
202+
Run `yarn test` to fire up the [Mockoon CLI](https://mockoon.com/cli/) mock API and run all [Playwright](https://playwright.dev/) tests. Don't worry, everything stops after testing has finished.
203+
204+
## License
205+
Licensed under [MIT](./LICENSE).

0 commit comments

Comments
 (0)