WIP (docs driven development) - Preview API

[erquhart]

Alrighty folks, we're going to go docs driven for the preview API!

You do not have to be a maintainer to review this and help shape the API.

Related to #1041.

How to review:

1. Read through the docs pages linked below.
2. Create a review from the perspective of a developer looking to implement this API. Ask yourself:
   • Can we do this better?
   • Will this API result in a positive developer experience?
   • Is anything not covered by the API that should be?
3. Resist the urge to focus on grammar, style, and typos. That comes way later.

I'll link live pages that are ready for review below. Feel free to go over files in this PR that are not linked below, just know that they're not considered ready for any actual review.

Let's get it 💪

---

Ready for Review

• Quick start previews guide
• Template compiler guide

[verythorough]

Deploy preview for netlify-cms-www ready!

Built with commit 95e64b3

https://deploy-preview-1311--netlify-cms-www.netlify.com

[verythorough]

Deploy preview for cms-demo ready!

Built with commit 95e64b3

https://deploy-preview-1311--cms-demo.netlify.com

[Benaiah]

The description above has two asterisks (**brand new**) but there's only one here (*brand new*).

[tech4him1]

Will we allow the preview template to be pulled in via a filename?

CMS.registerPreviewTemplate('blog', 'template.hbs');

If so, do we need to allow an option/switch for that so that we can easily differentiate between filenames and templates?

[erquhart]

I wasn't planning on it - the case where someone can actually use production templates in the CMS is pretty rare. It's most likely to be possible for projects using React components as templates, but in that case the file is going to be ES6/JSX, so the CMS still can't use it as is. We'd also have to grab templates via GitHub since they wouldn't be available in the deployed site.

[erquhart]

Although this could also be used buy sites that do have custom templates for the CMS, but no build system for easily importing them in a registration script. This is worth considering.

[loremipson]

This line is missing the </div>

[erquhart]

Good catch!

We'll likely change look and feel and improve presentation before this goes out - the big thing to review here is the new API itself, and whether it's adequate.

[erquhart]

The big change so far:

Current
We provide an immutable map of field values, separate getter functions for specific bits like a renderable image URI or the field preview, and a general metadata object to collect secondary field data.

Proposed
Preview templates receive an object of fields, with nested fields directly in their parents. Each field that does not contain children has the values value, preview, and data.

What this means

• getAsset is replaced by a src getter in a field's data property
• fieldsMetaData is also replaced by each field's individual data property
• widgetFor and widgetsFor are replaced by each field's individual preview property

Other benefits

• Simple template languages like Mustache can be used with full Preview API functionality

Notes

• A new guiding principle: the preview pane does a microscopic, transient version of what a static site generator does - converts some raw content and a template to HTML. The SSG only has raw values to work with. So when we provide "privileged" extras like widget previews and field data to the preview pane, they must only serve to bolster convenience and performance. For the most part, the preview template should have access to everything it needs to render with just raw values.
• Whenever the question comes, "how do I get xyz in my preview template", our first response should be "how does the SSG get it?". Consider relations, for example, where the SSG only has a raw field value from the related entry.

(Developing)

[erquhart]

Closing as stale, will re-open when ready.