Update Docs “customization”

This commit is contained in:
Shawn Erquhart 2017-12-09 03:28:57 -05:00
parent c8a9607f79
commit 1445a3da71

View File

@ -2,7 +2,6 @@
title: Custom Previews title: Custom Previews
position: 50 position: 50
--- ---
# Customizing the Preview Pane # Customizing the Preview Pane
The NetlifyCMS exposes a `window.CMS` global object that you can use to register custom widgets, previews and editor plugins. The available customization methods are: The NetlifyCMS exposes a `window.CMS` global object that you can use to register custom widgets, previews and editor plugins. The available customization methods are:
@ -29,13 +28,15 @@ CMS.registerPreviewStyle(file);
* **file:** css file path * **file:** css file path
**Example:** **Example:**
```html ```html
// index.html // index.html
<script src="https://unpkg.com/netlify-cms@^0.7.0/dist/cms.js"></script> <script src="https://unpkg.com/netlify-cms@^1.0.0/dist/cms.js"></script>
<script> <script>
CMS.registerPreviewStyle("/example.css"); CMS.registerPreviewStyle("/example.css");
</script> </script>
``` ```
```css ```css
/* example.css */ /* example.css */
@ -49,11 +50,8 @@ body {
body { body {
padding: 20px; padding: 20px;
} }
``` ```
## `registerPreviewTemplate` ## `registerPreviewTemplate`
Registers a template for a collection. Registers a template for a collection.
@ -68,11 +66,9 @@ Registers a template for a collection.
* widgetFor: Returns the appropriate widget preview component for a given field. * widgetFor: Returns the appropriate widget preview component for a given field.
* [widgetsFor](#lists-and-objects): Returns an array of objects with widgets and associated field data. For use with list and object type entries. * [widgetsFor](#lists-and-objects): Returns an array of objects with widgets and associated field data. For use with list and object type entries.
* getAsset: Returns the correct filePath or in-memory preview for uploaded images. * getAsset: Returns the correct filePath or in-memory preview for uploaded images.
**Example:** **Example:**
```html ```html
<script src="https://unpkg.com/netlify-cms@^0.7.0/dist/cms.js"></script> <script src="https://unpkg.com/netlify-cms@^1.0.0/dist/cms.js"></script>
<script> <script>
var PostPreview = createClass({ var PostPreview = createClass({
render: function() { render: function() {
@ -86,23 +82,19 @@ Registers a template for a collection.
); );
} }
}); });
CMS.registerPreviewTemplate("posts", PostPreview); CMS.registerPreviewTemplate("posts", PostPreview);
</script> </script>
``` ```
### Lists and Objects ### Lists and Objects
The API for accessing the individual fields of list- and object-type entries is similar to the API 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 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 nested fields is facilitated through the `widgetsFor` function, which is passed to the preview
template component during render. template component during render.
**Note**: as is often the case with the NetlifyCMS API, arrays and objects are created with **Note**: as is often the case with the NetlifyCMS API, arrays and objects are created with
Immutable.js. If some of the methods that we use are unfamiliar, such as `getIn`, check out Immutable.js. If some of the methods that we use are unfamiliar, such as `getIn`, check out
[their docs](https://facebook.github.io/immutable-js/docs/#/) to get a better understanding. [their docs](https://facebook.github.io/immutable-js/docs/#/) to get a better understanding.
**List Example:** **List Example:**
```html ```html
<script> <script>
var AuthorsPreview = createClass({ var AuthorsPreview = createClass({
@ -121,13 +113,13 @@ Registers a template for a collection.
// }] // }]
// //
// Templating would look something like this: // Templating would look something like this:
render: function() { render: function() {
return h('div', {}, return h('div', {},
// This is a static header that would only be rendered once for the entire list // This is a static header that would only be rendered once for the entire list
h('h1', {}, 'Authors'), h('h1', {}, 'Authors'),
// Here we provide a simple mapping function that will be applied to each // Here we provide a simple mapping function that will be applied to each
// object in the array of authors // object in the array of authors
this.props.widgetsFor('authors').map(function(author, index) { this.props.widgetsFor('authors').map(function(author, index) {
@ -140,13 +132,11 @@ Registers a template for a collection.
); );
} }
}); });
CMS.registerPreviewTemplate("authors", AuthorsPreview); CMS.registerPreviewTemplate("authors", AuthorsPreview);
</script> </script>
``` ```
**Object Example:** **Object Example:**
```html ```html
<script> <script>
var GeneralPreview = createClass({ var GeneralPreview = createClass({
@ -162,38 +152,35 @@ Registers a template for a collection.
var entry = this.props.entry; var entry = this.props.entry;
var title = entry.getIn(['data', 'site_title']); var title = entry.getIn(['data', 'site_title']);
var posts = entry.getIn(['data', 'posts']); var posts = entry.getIn(['data', 'posts']);
return h('div', {}, return h('div', {},
h('h1', {}, title), h('h1', {}, title),
h('dl', {}, h('dl', {},
h('dt', {}, 'Posts on Frontpage'), h('dt', {}, 'Posts on Frontpage'),
h('dd', {}, this.props.widgetsFor('posts').getIn(['widgets', 'front_limit']) || 0), h('dd', {}, this.props.widgetsFor('posts').getIn(['widgets', 'front_limit']) || 0),
h('dt', {}, 'Default Author'), h('dt', {}, 'Default Author'),
h('dd', {}, this.props.widgetsFor('posts').getIn(['data', 'author']) || 'None'), h('dd', {}, this.props.widgetsFor('posts').getIn(['data', 'author']) || 'None'),
) )
); );
} }
}); });
CMS.registerPreviewTemplate("general", GeneralPreview); CMS.registerPreviewTemplate("general", GeneralPreview);
</script> </script>
``` ```
### Accessing Metadata ### Accessing Metadata
Preview Components also receive an additional prop: `fieldsMetaData`. It contains aditional information (besides the plain plain textual value of each field) that can be useful for preview purposes. Preview Components also receive an additional prop: `fieldsMetaData`. It contains aditional information (besides the plain plain textual value of each field) that can be useful for preview purposes.
For example, the Relation widget passes the whole selected relation data in `fieldsMetaData`. For example, the Relation widget passes the whole selected relation data in `fieldsMetaData`.
```js ```js
export default class ArticlePreview extends React.Component { export default class ArticlePreview extends React.Component {
render() { render() {
const {entry, fieldsMetaData} = this.props; const {entry, fieldsMetaData} = this.props;
const author = fieldsMetaData.getIn(['authors', data.author]); const author = fieldsMetaData.getIn(['authors', data.author]);
return <article><h2>{ entry.getIn(['data', 'title']) }</h2> return <article><h2>{ entry.getIn(['data', 'title']) }</h2>
{author &&<AuthorBio author={author.toJS()}/>} {author &&<AuthorBio author={author.toJS()}/>}
</article> </article>
} }
} }
``` ```