https://github.com/swup/custom-payload-plugin
A swup plugin for sending custom payload formats 📦
https://github.com/swup/custom-payload-plugin
json payload plugin server swup
Last synced: 2 months ago
JSON representation
A swup plugin for sending custom payload formats 📦
- Host: GitHub
- URL: https://github.com/swup/custom-payload-plugin
- Owner: swup
- License: mit
- Created: 2020-11-29T01:12:15.000Z (over 5 years ago)
- Default Branch: master
- Last Pushed: 2023-07-26T10:13:24.000Z (almost 3 years ago)
- Last Synced: 2025-10-06T02:26:41.136Z (9 months ago)
- Topics: json, payload, plugin, server, swup
- Language: JavaScript
- Homepage: https://swup.js.org/plugins/custom-payload-plugin
- Size: 132 KB
- Stars: 0
- Watchers: 2
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# Swup Custom Payload Plugin
A [swup](https://swup.js.org/) plugin for sending custom payload formats.
**🪦 Retired: This plugin is no longer supported in swup 4. Keep using swup 3 if you
require custom payloads.**
Allow receiving custom data formats on swup requests. Great for sending only the actually updated
content as JSON, reducing response size and speeding up page load. To identify requests requiring a
custom payload, check if the `X-Requested-With` header is set to `swup`.
## Installation
Install the plugin from npm and import it into your bundle.
```bash
npm install @swup/custom-payload-plugin
```
```js
import SwupCustomPayloadPlugin from '@swup/custom-payload-plugin';
```
Or include the minified production file from a CDN:
```html
```
## Usage
To run this plugin, include an instance in the swup options.
Pass in a `generatePageObject` function that receives a server request object,
parses its response data and and returns an object with page data expected by
swup. See below for the required structure and usage examples.
```javascript
const swup = new Swup({
plugins: [
new SwupCustomPayloadPlugin({
generatePageObject: (request) => {
/* [parse data from response here] */
return { title, blocks, pageClass, originalContent };
}
})
]
});
```
## Payload → Page object
The returned page object must include the new page's title and all its content
blocks. Other properties might be required to ensure proper functioning of
additional plugins in use by the site.
| Property | Required? | Type | Content | Notes |
| ----------------- | ------------ | --------------------- | ----------------------------------------------------------------------------------------------- | ----------------------------- |
| **`title`** | **required** | string | Title of the new page | |
| **`blocks`** | **required** | array of HTML strings | Containers of the new page, in the correct order (as marked by `[data-swup]` attributes in DOM) | |
| `pageClass` | | string | Class name(s) of the new page's body tag | Required by Body Class Plugin |
| `originalContent` | | string | Full HTML response of the new page | Required by Head Plugin |
## Example
This example shows how to parse a JSON response from the server and return the
correct data expected by swup.
Given this custom JSON payload:
```json
{
"title": "About",
"template": "about",
"containers": [
"
About
Lorem ipsum dolor sit amet
",
"HomeAbout"
]
}
```
This function will parse and prepare the page data for swup:
```js
function generatePageObject({ response }) {
const { title, template, containers } = JSON.parse(response);
return {
title: title,
blocks: containers,
pageClass: template
};
}
```