Skip to content

Commit 4b7d245

Browse files
johannschopplichjohannschopplich
committed
fix: rename overwriteContent to replaceValues 
1 parent 14ae7c9 commit 4b7d245

File tree

2 files changed

+75
-45
lines changed

2 files changed

+75
-45
lines changed

‎README.md‎

Lines changed: 72 additions & 42 deletions
Original file line numberDiff line numberDiff line change
@@ -19,14 +19,34 @@ This plugins enhances your Kirby site with headless capabilities. It can either
1919
- 😵‍💫 Seamless experience without CORS issues
2020
- 🍢 Express-esque [API builder](#api-builder) with middleware support
2121

22+
## Table of Contents
23+
24+
- [Use Cases](#use-cases)
25+
- [Requirements](#requirements)
26+
- [Installation](#installation)
27+
- [Setup](#setup)
28+
- [Usage](#usage)
29+
- [Private vs. Public API](#private-vs-public-api)
30+
- [Cross Origin Resource Sharing (CORS)](#cross-origin-resource-sharing-cors)
31+
- [Kirby Query Language (KQL)](#kirby-query-language-kql)
32+
- [Templates](#templates)
33+
- [Panel Settings](#panel-settings)
34+
- [Field Methods](#field-methods)
35+
- [`toResolvedBlocks()`](#toresolvedblocks)
36+
- [`resolvePermalinks()`](#resolvepermalinks)
37+
- [Page Methods](#page-methods)
38+
- [`i18nMeta()`](#i18nmeta)
39+
- [API Builder](#api-builder)
40+
- [FAQ](#faq)
41+
2242
## Use Cases
2343

2444
This plugin is designed for developers who want to leverage Kirby's backend to serve content to a frontend application, static site generator, or mobile app. You can either opt-in to headless functionality for your existing Kirby site or use this plugin to build a headless-first CMS from scratch.
2545

2646
Here are scenarios where the Kirby Headless plugin is particularly useful:
2747

2848
- 1️⃣ If you prefer to query data using the [Kirby Query Language](#kirby-query-language-kql).
29-
- 2️⃣ If you want to use [Kirby's default template system](#templates) to output JSON.
49+
- 2️⃣ If you want to use [Kirby's default template system](#templates) to output JSON instead of HTML.
3050

3151
Detailed instructions on how to use these features can be found in the [usage](#usage) section.
3252

@@ -75,6 +95,43 @@ This will make all page templates return JSON instead of HTML by [defining globa
7595

7696
## Usage
7797

98+
### Private vs. Public API
99+
100+
It is recommended to secure your API with a token. To do so, set the `headless.token` Kirby configuration option:
101+
102+
```php
103+
# /site/config/config.php
104+
return [
105+
'headless' => [
106+
'token' => 'test'
107+
]
108+
];
109+
```
110+
111+
You will then have to provide the HTTP header `Authentication: Bearer ${token}` with each request.
112+
113+
> [!WARNING]
114+
> Without a token your page content will be publicly accessible to everyone.
115+
116+
### Cross Origin Resource Sharing (CORS)
117+
118+
CORS is enabled by default. You can enhance the default CORS configuration by setting the following options in your `config.php`:
119+
120+
```php
121+
# /site/config/config.php
122+
return [
123+
'headless' => [
124+
// Default CORS configuration
125+
'cors' => [
126+
'allowOrigin' => '*',
127+
'allowMethods' => 'GET, POST, OPTIONS',
128+
'allowHeaders' => 'Accept, Content-Type, Authorization, X-Language',
129+
'maxAge' => '86400',
130+
]
131+
]
132+
];
133+
```
134+
78135
### Kirby Query Language (KQL)
79136

80137
It is common to authenticate API requests with a token, which is not possible with the default KQL endpoint. Thus, this plugin adds a new KQL endpoint under `/api/kql` that supports bearer token authentication and query response caching.
@@ -143,43 +200,6 @@ To **disable** the bearer token authentication for your Kirby instance and inste
143200
> [!NOTE]
144201
> The KQL default endpoint `/api/query` remains using basic authentication and also infers the `kql.auth` config option.
145202
146-
### Private vs. Public API
147-
148-
It is recommended to secure your API with a token. To do so, set the `headless.token` Kirby configuration option:
149-
150-
```php
151-
# /site/config/config.php
152-
return [
153-
'headless' => [
154-
'token' => 'test'
155-
]
156-
];
157-
```
158-
159-
You will then have to provide the HTTP header `Authentication: Bearer ${token}` with each request.
160-
161-
> [!WARNING]
162-
> Without a token your page content will be publicly accessible to everyone.
163-
164-
### Cross Origin Resource Sharing (CORS)
165-
166-
CORS is enabled by default. You can enhance the default CORS configuration by setting the following options in your `config.php`:
167-
168-
```php
169-
# /site/config/config.php
170-
return [
171-
'headless' => [
172-
// Default CORS configuration
173-
'cors' => [
174-
'allowOrigin' => '*',
175-
'allowMethods' => 'GET, POST, OPTIONS',
176-
'allowHeaders' => 'Accept, Content-Type, Authorization, X-Language',
177-
'maxAge' => '86400',
178-
]
179-
]
180-
];
181-
```
182-
183203
### Templates
184204

185205
Write templates as you would in any other Kirby project. But instead of returning HTML, they return JSON. The internal route handler adds the correct content type and also handles caching (if enabled).
@@ -367,13 +387,13 @@ return [
367387

368388
#### Mutate Blocks Values
369389

370-
By default, resolved fields don't mutate source fields of the blocks array. Instead, the resolved content is stored in the `resolved` key of each block. If you want to overwrite the field value with the resolved content, you can set the `overwriteContent` option to `true`:
390+
By default, resolved fields don't mutate source fields of the blocks array. Instead, the resolved content is stored in the `resolved` key of each block. If you want to overwrite the field value with the resolved content, you can set the `replaceValues` option to `true`:
371391

372392
```php
373393
# /site/config/config.php
374394
return [
375395
'blocksResolver' => [
376-
'overwriteContent' => true
396+
'replaceValues' => true
377397
]
378398
];
379399
```
@@ -426,9 +446,19 @@ return [
426446

427447
The `i18nMeta()` method returns an array including the title and URI for the current page in all available languages. This is useful for the frontend to build a language switcher.
428448

429-
## Advanced
449+
**Type Declaration:**
450+
451+
```ts
452+
type I18nMeta = Record<
453+
string,
454+
{
455+
title: string
456+
uri: string
457+
}
458+
>
459+
```
430460
431-
### API Builder
461+
## API Builder
432462
433463
This headless starter includes an Express-esque API builder, defined in the [`JohannSchopplich\Headless\Api\Api` class](./src/classes/Api/Api.php). You can use it to re-use logic like handling a token or verifying some other incoming data.
434464

‎src/extensions/fieldMethods.php‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -48,7 +48,7 @@
4848
// Get already resolved images
4949
$resolved = $block->content()->get('resolved')->or([])->value();
5050

51-
if ($kirby->option('blocksResolver.overwriteContent', false)) {
51+
if ($kirby->option('blocksResolver.replaceValues', false)) {
5252
$block->content()->update([
5353
$key => $images->map($defaultResolver)->values()
5454
]);
@@ -99,7 +99,7 @@
9999
// Get already resolved images
100100
$resolved = $block->content()->get('resolved')->or([])->value();
101101

102-
if ($kirby->option('blocksResolver.overwriteContent', false)) {
102+
if ($kirby->option('blocksResolver.replaceValues', false)) {
103103
$block->content()->update([
104104
$key => $pages->map($defaultResolver)->values()
105105
]);
@@ -130,7 +130,7 @@
130130
$field = $block->content()->get($key);
131131
$resolved = $block->content()->get('resolved')->or([])->value();
132132

133-
if ($kirby->option('blocksResolver.overwriteContent', false)) {
133+
if ($kirby->option('blocksResolver.replaceValues', false)) {
134134
$block->content()->update([
135135
$key => $resolver($field, $block)
136136
]);

0 commit comments

Comments
 (0)