Feature/docs (#67)
This commit is contained in:
Daniel Lautzenheiser
committed by
GitHub
GitHub
parent
7a1ec55a5c
commit
81ca566b5e
157
website/content/docs/custom-previews.mdx
Normal file
157
website/content/docs/custom-previews.mdx
Normal file
@ -0,0 +1,157 @@
|
||||
---
|
||||
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>
|
||||
```
|
||||
Reference in New Issue
Block a user