gcg/static-cms
0
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

updates docs

Browse Source
This commit is contained in:
Brian 'bdougie' Douglas
2017-03-28 08:01:03 -07:00
parent b7f5ab255e
commit d7b740f1c5
12 changed files with 546 additions and 458 deletions
Download Patch File Download Diff File Expand all files Collapse all files

0
docs/architecture.md Normal file → Executable file
View File

18
docs/configuration.md Normal file
View File

@ -0,0 +1,18 @@
# Configuring your site
## Widgets
Widgets define the data type and interface for entry fields. Netlify CMS comes with several built-in widgets, including:
Widget | UI | Data Type
--- | --- | ---
`string` | text input | string
`text` | text area input | plain text, multiline input
`number` | text input with `+` and `-` buttons | number
`markdown` | rich text editor with raw option | markdown-formatted string
`datetime` | date picker widget | ISO date string
`image` | file picker widget with drag-and-drop | file path saved as string, image uploaded to media folder
`hidden` | No UI | Hidden element, typically only useful with a `default` attribute
`list` | text input | strings separated by commas
We’re always adding new widgets, and you can also [create your own](/docs/extending).

9
docs/contributor-guide.md Normal file
View File

@ -0,0 +1,9 @@
# Welcome, contributors!
We're hoping that Netlify CMS will do for the [JAMstack](https://www.jamstack.org) what WordPress did for dynamic sites back in the day. We know we can't do that without building a thriving community of contributors and users, and we'd love to have you join us.
While we work on building this page (and you can help!), here are some links with more information about getting involved:
* [Project Roadmap](https://github.com/netlify/netlify-cms/projects/3)
* [Code of Conduct](https://github.com/netlify/netlify-cms/blob/master/CODE_OF_CONDUCT.md)
* [Setup instructions and Contribution Guidelines](https://github.com/netlify/netlify-cms/blob/master/CONTRIBUTING.md)

194
docs/customization.md Normal file
View File

@ -0,0 +1,194 @@
## Customizing the Preview Pane
The NetlifyCMS exposes an `window.CMS` global object that you can use to register custom widgets, previews and editor plugins. The available customization methods are:
* **registerPreviewStyle** Register a custom stylesheet to use on the preview pane.
* **registerPreviewTemplate** Registers a template for a collection.
Explore the [NetlifyCMS GitHub example](https://github.com/netlify/netlify-cms/blob/9ced3f16c8bcc3d1a36773b126842d023c589eaf/example/index.html#L90-L91) has a working example to review on GitHub.
### React Components inline interaction
NetlifyCMS is a collection of React components and exposes two constructs globally to allow you to create components inline: ‘createClass’ and ‘h’ (alias for React.createElement).
## `registerPreviewStyle`
Register a custom stylesheet to use on the preview pane.
```js
CMS.registerPreviewStyle(file);
```
**Params:**
* **file:** css file path
**Example:**
```html
// index.html
<script src="https://unpkg.com/netlify-cms@^0.x/dist/cms.js"></script>
<script>
CMS.registerPreviewStyle("/example.css");
</script>
```
```css
/* example.css */
html,
body {
color: #444;
font-size: 14px;
font-family: 'Helvetica Neue', Helvetica, Arial, sans-serif;
}
body {
padding: 20px;
}
```
## `registerPreviewTemplate`
Registers a template for a collection.
`CMS.registerPreviewTemplate(collection, react_component);`
**Params:**
* collection: The name of the collection which this preview component will be used for.
* react_component: A React component that renders the collection data. Four props will be passed to your component during render:
* entry: Immutable collection containing the entry data.
* 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.
* getAsset: Returns the correct filePath or in-memory preview for uploaded images.
**Example:**
```html
<script src="https://unpkg.com/netlify-cms@^0.x/dist/cms.js"></script>
<script>
var PostPreview = createClass({
render: function() {
var entry = this.props.entry;
var image = entry.getIn(['data', 'image']);
var bg = this.props.getAsset(image);
return h('div', {},
h('h1', {}, entry.getIn(['data', 'title'])),
h('img', {src: bg.toString()}),
h('div', {"className": "text"}, this.props.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.
**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
[their docs](https://facebook.github.io/immutable-js/docs/#/) to get a better understanding.
**List Example:**
```html
<script>
var AuthorsPreview = createClass({
// For list fields, the widgetFor function returns an array of objects
// which 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: { name: 'Mathias', description: 'Co-Founder'},
// widgets: { name: (<WidgetComponent>), description: (WidgetComponent>)}
// },
// {
// data: { name: 'Chris', description: 'Co-Founder'},
// widgets: { name: (<WidgetComponent>), description: (WidgetComponent>)}
// }]
//
// Templating would look something like this:
render: function() {
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
this.props.widgetsFor('authors').map(function(author, index) {
return h('div', {key: index},
h('hr', {}),
h('strong', {}, author.getIn(['data', 'name'])),
author.getIn(['widgets', 'description'])
);
})
);
}
});
CMS.registerPreviewTemplate("authors", AuthorsPreview);
</script>
```
**Object Example:**
```html
<script>
var GeneralPreview = createClass({
// 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>)}
// }
render: function() {
var entry = this.props.entry;
var title = entry.getIn(['data', 'site_title']);
var posts = entry.getIn(['data', 'posts']);
return h('div', {},
h('h1', {}, title),
h('dl', {},
h('dt', {}, 'Posts on Frontpage'),
h('dd', {}, this.props.widgetsFor('posts').getIn(['widgets', 'front_limit']) || 0),
h('dt', {}, 'Default Author'),
h('dd', {}, this.props.widgetsFor('posts').getIn(['data', 'author']) || 'None'),
)
);
}
});
CMS.registerPreviewTemplate("general", GeneralPreview);
</script>
```
### 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.
For example, the Relation widget passes the whole selected relation data in fieldsMetaData.
```js
export default class ArticlePreview extends React.Component {
render() {
const {entry, fieldsMetaData} = this.props;
const author = fieldsMetaData.getIn(['authors', data.author]);
return <article><h2>{ entry.getIn(['data', 'title']) }</h2>
{author &&<AuthorBio author={author.toJS()}/>}
</article>
}
}
```

42
docs/editorial-workflow.md Executable file
View File

@ -0,0 +1,42 @@
# Editorial Workflow
## Overview
By default, all entries created or edited in the Netlify CMS are committed directly into the main repository branch.
Alternatively, you can enable an optional "Editorial Workflow" mode that allows for more control over the content publishing phases. All unpublished entries will be arranged in a board according to their status, and they can be further reviewed and edited before going live.
![Editorial workflow](https://cloud.githubusercontent.com/assets/33676/19452442/d10d9002-948f-11e6-9463-06955b6c15c8.png)
From a technical perspective, the workflow translates editor UI actions into common Git commands:
Actions in Netlify UI... | Perform these Git actions
--- | ---
Save draft | Commits to a new branch, and opens a pull request
Edit draft | Pushes another commit to the draft branch/pull request
Approve and publish draft | Merges pull request and deletes branch
## Adding to your site
To enable the editorial workflow, add this line to your `admin/config.yml` file:
``` yaml
publish_mode: editorial_workflow
```
There are no other configuration options right now. There are always three possible statuses, and new branch names are created according to the pattern `cms/collectionName-entrySlug`.
## About metadata
Netlify CMS embraces the idea of Git-as-backend for storing metadata. The first time it runs with the editorial_workflow setup, it creates a new ref called `meta/_netlify_cms`, pointing to an empty, orphan tree.
Actual data are stored in individual `json` files committed to this three.
## Implementation
Instead of adding logic to `CollectionPage` and `EntryPage`, the Editorial Workflow is implemented as Higher Order Components, adding UI and dispatching additional actions.
Furthermore, all editorial workflow state is managed in Redux - there's an `actions/editorialWorkflow.js` and a `reducers/editorialWorkflow.js` files.

55
docs/editorial_workflow.md
View File

@ -1,55 +0,0 @@
# Editorial Workflow
## Overview
The Netlify CMS has an optional "Editorial Workflow" mode that let's allows for more control over the content publishing phases.
By default, all entries created or edited in the Netlify CMS are committed directly into the main repository branch - which means your live site will be updated (that is, assuming your site is hosted on Netlify or you have your own continuous deployment setup).
With the Editorial Workflow configured, entries can have a 'Draft', 'Waiting for Review' or 'Waiting to go live' status.
This works transparently from the CMS user perspective. All unpublished entries will be arranged in a board according to their status, and they can be further reviewed and edited before going live.
![Editorial-workflow](https://cloud.githubusercontent.com/assets/33676/19452442/d10d9002-948f-11e6-9463-06955b6c15c8.png)
From a technical perspective, this means that instead of publishing a new or edited entry directly into the default repository branch, Netlify CMS will:
* Create a new Branch before committing the new/changed files.
* Save some metadata information regarding the new entry.
* Open a Pull Request to merge the edited content.
Once on "Waiting to go live", a merge into the main branch can be triggered directly from the Netlify CMS UI.
## Configuring Editorial Workflow on your site.
Just add `publish_mode: editorial_workflow` in your config.yaml file. For example:
```yaml
backend:
name: github
repo: repo/mysite
publish_mode: editorial_workflow
collections:
- name: articles
label: "Articles" # Used in the UI, ie.: "New Post"
# etc (Omitted for brevity)
```
There are no other configuration options right now: There are always three possible status, and the new branches names are created according to the pattern `cms/collectionName-entrySlug`.
## About metadata
Netlify CMS embraces the idea of GIT-as-backend for storing metadata. The first time it runs with the editorial_workflow setup, it creates a new ref called `meta/_netlify_cms`, pointing to an empty, orphan tree.
Actual data are stored in individual `json` files committed to this three.
## Implementation
Instead of adding logic to `CollectionPage` and `EntryPage`, the Editorial Workflow is implemented as Higher Order Components, adding UI and dispatching additional actions.
Furthermore, all editorial workflow state is managed in Redux - there's an `actions/editorialWorkflow.js` and a `reducers/editorialWorkflow.js` files.

211
docs/extending.md Normal file → Executable file
View File

@ -1,195 +1,36 @@
# Extending Netlify CMS
The Netlify CMS exposes an `window.CMS` global object that you can use to register custom widgets, previews and editor plugins. The available methods are:
## Extending With Widgets
The NetlifyCMS exposes an `window.CMS` global object that you can use to register custom widgets, previews and editor plugins. The available widger extension methods are:
* **registerPreviewStyle** Register a custom stylesheet to use on the preview pane.
* **registerPreviewTemplate** Registers a template for a collection.
* **registerWidget** lets you register a custom widget.
* **registerEditorComponent** lets you add a block component to the Markdown editor
**Writing React Components inline**
### Writing React Components inline
Both registerPreviewTemplate and registerWidget requires you to provide a React component. If you have a build process in place for your project, it is possible to integrate webpack and Babel for a complete React build flow.
The registerWidget requires you to provide a React component. If you have a build process in place for your project, it is possible to integrate
Although possible, it may be cumbersome or even impractical to add a React build phase. For this reason, Netlify CMS exposes two React constructs globally to allow you to create components inline: ‘createClass’ and ‘h’ (alias for React.createElement).
## `registerPreviewStyle`
Register a custom stylesheet to use on the preview pane.
`CMS.registerPreviewStyle(file);`
**Params:**
* file: css file path.
**Example:**
`CMS.registerPreviewStyle("/example.css");`
## `registerPreviewTemplate`
Registers a template for a collection.
`CMS.registerPreviewTemplate(collection, react_component);`
**React Component Props:**
* collection: The name of the collection which this preview component will be used for.
* react_component: A React component that renders the collection data. Four props will be passed to your component during render:
* entry: Immutable collection containing the entry data.
* 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.
* getAsset: Returns the correct filePath or in-memory preview for uploaded images.
**Example:**
```html
<script>
var PostPreview = createClass({
render: function() {
var entry = this.props.entry;
var image = entry.getIn(['data', 'image']);
var bg = this.props.getAsset(image);
return h('div', {},
h('h1', {}, entry.getIn(['data', 'title'])),
h('img', {src: bg.toString()}),
h('div', {"className": "text"}, this.props.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.
**Note**: as is often the case with the Netlify CMS API, arrays and objects are created with
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.
**List Example:**
```html
<script>
var AuthorsPreview = createClass({
// For list fields, the widgetFor function returns an array of objects
// which 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: { name: 'Mathias', description: 'Co-Founder'},
// widgets: { name: (<WidgetComponent>), description: (WidgetComponent>)}
// },
// {
// data: { name: 'Chris', description: 'Co-Founder'},
// widgets: { name: (<WidgetComponent>), description: (WidgetComponent>)}
// }]
//
// Templating would look something like this:
render: function() {
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
this.props.widgetsFor('authors').map(function(author, index) {
return h('div', {key: index},
h('hr', {}),
h('strong', {}, author.getIn(['data', 'name'])),
author.getIn(['widgets', 'description'])
);
})
);
}
});
CMS.registerPreviewTemplate("authors", AuthorsPreview);
</script>
```
**Object Example:**
```html
<script>
var GeneralPreview = createClass({
// 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>)}
// }
render: function() {
var entry = this.props.entry;
var title = entry.getIn(['data', 'site_title']);
var posts = entry.getIn(['data', 'posts']);
return h('div', {},
h('h1', {}, title),
h('dl', {},
h('dt', {}, 'Posts on Frontpage'),
h('dd', {}, this.props.widgetsFor('posts').getIn(['widgets', 'front_limit']) || 0),
h('dt', {}, 'Default Author'),
h('dd', {}, this.props.widgetsFor('posts').getIn(['data', 'author']) || 'None'),
)
);
}
});
CMS.registerPreviewTemplate("general", GeneralPreview);
</script>
```
### 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.
For example, the Relation widget passes the whole selected relation data in fieldsMetaData.
```js
export default class ArticlePreview extends React.Component {
render() {
const {entry, fieldsMetaData} = this.props;
const author = fieldsMetaData.getIn(['authors', data.author]);
return <article>
<h2>{ entry.getIn(['data', 'title']) }</h2>
{author && <AuthorBio author={author.toJS()}/>}
</article>
}
}
```
Although possible, it may be cumbersome or even impractical to add a React build phase. For this reason, NetlifyCMS exposes two constructs globally to allow you to create components inline: ‘createClass’ and ‘h’ (alias for React.createElement).
## `registerWidget`
lets you register a custom widget.
Register a custom widget.
`CMS.registerWidget(field, control, [preview])`
```js
CMS.registerWidget(field, control, \[preview\])
```
**Params:**
* field: The field type which this widget will be used for.
* control: A React component that renders the editing interface for this field. Two props will be passed:
* value: The current value for this field.
* onChange: Callback function to update the field value.
* preview (optional): A React component that renders the preview of how the content will look. A `value` prop will be passed to this component.
* **field:** The field type which this widget will be used for.
* **control:** A React component that renders the editing interface for this field. Two props will be passed:
* **value:** The current value for this field.
* **onChange:** Callback function to update the field value.
* **preview (optional):** A React component that renders the preview of how the content will look. A `value` prop will be passed to this component.
**Example:**
```html
<script src="https://unpkg.com/netlify-cms@^0.x/dist/cms.js"></script>
<script>
var CategoriesControl = createClass({
handleChange: function(e) {
@ -208,17 +49,19 @@ CMS.registerWidget('categories', CategoriesControl);
## `registerEditorComponent`
lets your register a block level component for the Markdown editor
Register a block level component for the Markdown editor
`CMS.registerEditorComponent(definition)`
CMS.registerEditorComponent(definition)
**Params**
* definition: The component definition, must specify: id, label, fields, patterns, fromBlock, toBlock, toPreview
* **definition:** The component definition, must specify: id, label, fields, patterns, fromBlock, toBlock, toPreview
**Example:**
```js
```html
<script src="https://unpkg.com/netlify-cms@^0.x/dist/cms.js"></script>
<script>
CMS.registerEditorComponent({
// Internal id of the component
id: "youtube",
@ -227,7 +70,7 @@ CMS.registerEditorComponent({
// Fields the user need to fill out when adding an instance of the component
fields: [{name: 'id', label: 'Youtube Video ID', widget: 'string'}],
// Pattern to identify a block as being an instance of this component
pattern: /^{{<\s?youtube (\S+)\s?>}}/,
pattern: youtube (\S+)\s,
// Function to extract data elements from the regexp match
fromBlock: function(match) {
return {
@ -236,7 +79,7 @@ CMS.registerEditorComponent({
},
// Function to create a text block from an instance of this component
toBlock: function(obj) {
return '{{< youtube ' + obj.id + ' >}}';
return 'youtube ' + obj.id;
},
// Preview output for this component. Can either be a string or a React component
// (Component gives better render performance)
@ -246,4 +89,10 @@ CMS.registerEditorComponent({
);
}
});
</script>
```
**Result:**
![youtube-widget](/img/youtube-widget.png)

1
docs/intro.md Normal file → Executable file
View File

@ -112,3 +112,4 @@ Netlify CMS exposes a `window.CMS` global object that you can use to register cu
* `registerWidget` - registers a custom widget
* `registerEditorComponent` - adds a block component to the Markdown editor

1
docs/quick-start.md Normal file → Executable file
View File

@ -198,3 +198,4 @@ Based on this example, you can go through the post types in your site and add th
With your configuration complete, it's time to try it out! Go to `yoursite.com/admin` and complete the login prompt to access the admin interface. To add users, simply add them as collaborators on the GitHub repo.
Happy posting!

28
docs/test-drive.md Normal file
View File

@ -0,0 +1,28 @@
# Take a test drive
You can easily try out Netlify CMS by running it on a pre-configured starter site. Our example in the intro is the [Kaldi small business Hugo template](https://github.com/netlify-templates/kaldi-hugo-cms-template). Use the deploy button below to build and deploy your own copy of the repository:
[![Deploy to Netlify](https://www.netlify.com/img/deploy/button.svg)](https://app.netlify.com/start/deploy?repository=https://github.com/netlify-templates/kaldi-hugo-cms-template)
## Authenticate with GitHub
When the deploy completes, you can see your site, but in order to use the CMS, you'll need to set up authentication with GitHub.
First, register the site CMS as an authorized application with your GitHub account:
1. Go to your account **Settings** page on GitHub, and click **Oauth Applications** under **Developer Settings** (or use [this shortcut](https://github.com/settings/developers)).
2. Click **Register a new application**.
3. For the **Authorization callback URL**, enter `https://api.netlify.com/auth/done`. The other fields can contain anything you want.
![GitHub Oauth Application setup example](/img/github-oauth.png?raw=true)
When you complete the registration, you'll be given a **Client ID** and a **Client Secret** for the app. You'll need to add these to your Netlify project:
1. Go to your [**Netlify dashboard**](https://app.netlify.com/) and click on your project.
2. Click the **Access** tab.
3. Under **Authentication Providers**, click **Install Provider**.
4. Select GitHub and enter the **Client ID** and **Client Secret**, then save.
## Access the CMS
With the site deployed and authentication in place, you'll be able to enter the CMS by going to the URL of your new site and appending `/admin`.

0
docs/validation.md Normal file → Executable file
View File