158 lines
6.8 KiB
Plaintext
158 lines
6.8 KiB
Plaintext
|
---
|
||
|
|
group: Customization
|
||
|
|
title: Creating Custom Previews
|
||
|
|
weight: 50
|
||
|
|
---
|
||
|
|
|
||
|
|
The Static CMS exposes a `window.CMS` global object that you can use to register custom previews for an entire collection (or file within a file collection) via `registerPreviewTemplate`.
|
||
|
|
|
||
|
|
### React Components Inline
|
||
|
|
|
||
|
|
The `registerPreviewTemplate` requires you to provide a React component. If you have a build process in place for your project, it is possible to integrate with this build process.
|
||
|
|
|
||
|
|
However, although possible, it may be cumbersome or even impractical to add a React build phase. For this reason, Static CMS exposes some constructs globally to allow you to create components inline: `h` (alias for React.createElement) as well some basic hooks (`useState`, `useMemo`, `useEffect`, `useCallback`).
|
||
|
|
|
||
|
|
**NOTE**: `createClass` is still provided, allowing for the creation of react class components. However it has now been deprecated and will be removed in `v2.0.0`.
|
||
|
|
|
||
|
|
## Params
|
||
|
|
|
||
|
|
| Param | Type | Description |
|
||
|
|
| --------------- | ------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
||
|
|
| name | string | The name of the collection (or file for file collections) which this preview component will be used for<br /><ul><li>Folder collections: Use the name of the collection</li><li>File collections: Use the name of the file</li></ul> |
|
||
|
|
| react_component | [React Function Component](https://reactjs.org/docs/components-and-props.html) | A React functional component that renders the collection data. |
|
||
|
|
|
||
|
|
The following parameters will be passed to your `react_component` during render:
|
||
|
|
|
||
|
|
| Param | Type | Description |
|
||
|
|
| ---------- | -------------- | ---------------------------------------------------------------------------------------------------- |
|
||
|
|
| entry | object | Object with a `data` field that contains the current value of all widgets in the editor |
|
||
|
|
| document | Document | The document object the preview is within. If rendered with a frame, it will be the frame's document |
|
||
|
|
| window | Window | The window object the preview is within. If rendered with a frame, it will be the frame's window |
|
||
|
|
| getAsset | Async function | Function that given a url returns (as a promise) a loaded asset |
|
||
|
|
| widgetFor | Function | Given a field name, returns the rendered preview of that field's widget and value |
|
||
|
|
| widgetsFor | Function | Given a field name, returns the rendered previews of that field's nested child widgets and values |
|
||
|
|
|
||
|
|
### Example
|
||
|
|
|
||
|
|
```html
|
||
|
|
<script src="https://unpkg.com/@staticcms/core@%5E1.0.0/dist/static-cms-core.js"></script>
|
||
|
|
<script>
|
||
|
|
const PostPreview = ({ widgetFor, getAsset, entry }) => {
|
||
|
|
const [imageUrl, setImageUrl] = useState('');
|
||
|
|
const image = useMemo(() => entry.data.image, [entry.data.image]);
|
||
|
|
|
||
|
|
useEffect(() => {
|
||
|
|
let alive = true;
|
||
|
|
|
||
|
|
const loadImage = async () => {
|
||
|
|
const imageAsset = await getAsset(image);
|
||
|
|
if (alive) {
|
||
|
|
setImageUrl(imageAsset.toString());
|
||
|
|
}
|
||
|
|
};
|
||
|
|
|
||
|
|
loadImage();
|
||
|
|
|
||
|
|
return () => {
|
||
|
|
alive = false;
|
||
|
|
};
|
||
|
|
}, [image]);
|
||
|
|
|
||
|
|
return h(
|
||
|
|
'div',
|
||
|
|
{},
|
||
|
|
h('h1', {}, entry.data.title),
|
||
|
|
h('img', { src: imageUrl }),
|
||
|
|
h('div', { classtitle: 'text' }, widgetFor('body')),
|
||
|
|
);
|
||
|
|
});
|
||
|
|
|
||
|
|
CMS.registerPreviewTemplate('posts', PostPreview);
|
||
|
|
</script>
|
||
|
|
```
|
||
|
|
|
||
|
|
### Lists and Objects
|
||
|
|
|
||
|
|
The API for accessing the individual fields of list- and object-type entries is similar to the API for accessing fields in standard entries, but there are a few key differences. Access to these nested fields is facilitated through the `widgetsFor` function, which is passed to the preview template component during render.
|
||
|
|
|
||
|
|
**List Example:**
|
||
|
|
|
||
|
|
```html
|
||
|
|
<script>
|
||
|
|
// For list fields, the widgetFor function returns an array of objects
|
||
|
|
// that you can map over in your template. If our field is a list of
|
||
|
|
// authors containing two entries, with fields `name` and `description`,
|
||
|
|
// the return value of `widgetsFor` would look like this:
|
||
|
|
//
|
||
|
|
// [{
|
||
|
|
// data: { title: 'Mathias', description: 'Co-Founder'},
|
||
|
|
// widgets: { title: (<WidgetComponent>), description: (WidgetComponent>)}
|
||
|
|
// },
|
||
|
|
// {
|
||
|
|
// data: { title: 'Chris', description: 'Co-Founder'},
|
||
|
|
// widgets: { title: (<WidgetComponent>), description: (WidgetComponent>)}
|
||
|
|
// }]
|
||
|
|
//
|
||
|
|
// Templating would look something like this:
|
||
|
|
const AuthorsPreview = ({ widgetsFor }) => {
|
||
|
|
return h(
|
||
|
|
'div',
|
||
|
|
{},
|
||
|
|
|
||
|
|
// This is a static header that would only be rendered once for the entire list
|
||
|
|
h('h1', {}, 'Authors'),
|
||
|
|
|
||
|
|
// Here we provide a simple mapping function that will be applied to each
|
||
|
|
// object in the array of authors
|
||
|
|
widgetsFor('authors').map(function (author, index) {
|
||
|
|
return h(
|
||
|
|
'div',
|
||
|
|
{ key: index },
|
||
|
|
h('hr', {}),
|
||
|
|
h('strong', {}, author.data.name),
|
||
|
|
author.widgets.description,
|
||
|
|
);
|
||
|
|
}),
|
||
|
|
);
|
||
|
|
};
|
||
|
|
|
||
|
|
CMS.registerPreviewTemplate('authors', AuthorsPreview);
|
||
|
|
</script>
|
||
|
|
```
|
||
|
|
|
||
|
|
**Object Example:**
|
||
|
|
|
||
|
|
```html
|
||
|
|
<script>
|
||
|
|
// Object fields are simpler than lists - instead of `widgetsFor` returning
|
||
|
|
// an array of objects, it returns a single object. Accessing the shape of
|
||
|
|
// that object is the same as the shape of objects returned for list fields:
|
||
|
|
//
|
||
|
|
// {
|
||
|
|
// data: { front_limit: 0, author: 'Chris' },
|
||
|
|
// widgets: { front_limit: (<WidgetComponent>), author: (WidgetComponent>)}
|
||
|
|
// }
|
||
|
|
const GeneralPreview = ({ entry, widgetsFor }) => {
|
||
|
|
const title = entry.data.site_title;
|
||
|
|
const posts = entry.data.posts;
|
||
|
|
|
||
|
|
return h(
|
||
|
|
'div',
|
||
|
|
{},
|
||
|
|
h('h1', {}, title),
|
||
|
|
h(
|
||
|
|
'dl',
|
||
|
|
{},
|
||
|
|
h('dt', {}, 'Posts on Frontpage'),
|
||
|
|
h('dd', {}, widgetsFor('posts').widgets.front_limit || 0),
|
||
|
|
|
||
|
|
h('dt', {}, 'Default Author'),
|
||
|
|
h('dd', {}, widgetsFor('posts').data.author || 'None'),
|
||
|
|
),
|
||
|
|
);
|
||
|
|
};
|
||
|
|
|
||
|
|
CMS.registerPreviewTemplate('general', GeneralPreview);
|
||
|
|
</script>
|
||
|
|
```
|