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

docs: add migration guide (#685)

Browse Source
This commit is contained in:
Daniel Lautzenheiser
2023-04-05 16:32:17 -04:00
committed by GitHub
parent 22ccf41e3d
commit 94bbf14333
10 changed files with 359 additions and 114 deletions
Download Patch File Download Diff File Expand all files Collapse all files

49
packages/docs/content/docs/collection-overview.mdx
View File

@ -6,29 +6,30 @@ weight: 9
`collections` accepts a list of collection objects, each with the following options
| Name | Type | Default | Description |
| --------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| name | string | | Unique identifier for the collection, used as the key when referenced in other contexts (like the [relation widget](/docs/widgets/#relation)) |
| identifier_field | string | `'title'` | _Optional_. See [identifier_field](#identifier_field) below |
| label | string | `name` | _Optional_. Label for the collection in the editor UI |
| label_singular | string | `label` | _Optional_. Singular label for certain elements in the editor |
| icon | string | | _Optional_. Unique name of icon to use in main menu. See [Custom Icons](/docs/custom-icons) |
| description | string | | _Optional_. Text displayed below the label when viewing a collection |
| files or folder | [Collection Files](/docs/collection-types#file-collections)<br />\| [Collection Folder](/docs/collection-types#folder-collections) | | **Requires one of these**: Specifies the collection type and location; details in [Collection Types](/docs/collection-types) |
| filter | FilterRule | | _Optional_. Filter for [Folder Collections](/docs/collection-types#folder-collections) |
| create | boolean | `false` | _Optional_. **For [Folder Collections](/docs/collection-types#folder-collections) only**<br />`true` - Allows users to create new items in the collection |
| hide | boolean | `false` | _Optional_. `true` hides a collection in the CMS UI. Useful when using the relation widget to hide referenced collections |
| delete | boolean | `true` | _Optional_. `false` prevents users from deleting items in a collection |
| extension | string | | _Optional_. See [extension](#extension-and-format) below |
| format | 'yaml'<br />\| 'yml'<br />\| 'json'<br />\| 'frontmatter'<br />\| 'json-frontmatter'<br />\| 'yaml-frontmatter' | | _Optional_. See [format](#extension-and-format) below |
| frontmatter_delimiter | string<br />\| [string, string] | | _Optional_. See [frontmatter_delimiter](#frontmatter_delimiter) below |
| slug | string | | _Optional_. See [slug](#slug) below |
| fields (required) | Field | | _Optional_. See [fields](#fields) below. Ignored if [Files Collection](/docs/collection-types#file-collections) |
| editor | EditorConfig | | _Optional_. See [editor](#editor) below |
| summary | string | | _Optional_. See [summary](#summary) below |
| sortable_fields | SortableFields | | _Optional_. See [sortable_fields](#sortable_fields) below |
| view_filters | ViewFilter | | _Optional_. See [view_filters](#view_filters) below |
| view_groups | ViewGroup | | _Optional_. See [view_groups](#view_groups) below |
| Name | Type | Default | Description |
| --------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| name | string | | Unique identifier for the collection, used as the key when referenced in other contexts (like the [relation widget](/docs/widgets/#relation)) |
| identifier_field | string | `'title'` | _Optional_. See [identifier_field](#identifier_field) below |
| label | string | `name` | _Optional_. Label for the collection in the editor UI |
| label_singular | string | `label` | _Optional_. Singular label for certain elements in the editor |
| icon | string | | _Optional_. Unique name of icon to use in main menu. See [Custom Icons](/docs/custom-icons) |
| description | string | | _Optional_. Text displayed below the label when viewing a collection |
| files or folder | [Collection Files](/docs/collection-types#file-collections)<br />\| [Collection Folder](/docs/collection-types#folder-collections) | | **Requires one of these**: Specifies the collection type and location; details in [Collection Types](/docs/collection-types) |
| filter | FilterRule | | _Optional_. Filter for [Folder Collections](/docs/collection-types#folder-collections) |
| create | boolean | `false` | _Optional_. **For [Folder Collections](/docs/collection-types#folder-collections) only**<br />`true` - Allows users to create new items in the collection |
| hide | boolean | `false` | _Optional_. `true` hides a collection in the CMS UI. Useful when using the relation widget to hide referenced collections |
| delete | boolean | `true` | _Optional_. `false` prevents users from deleting items in a collection |
| extension | string | | _Optional_. See [extension](#extension-and-format) below |
| format | 'yaml'<br />\| 'yml'<br />\| 'json'<br />\| 'frontmatter'<br />\| 'json-frontmatter'<br />\| 'yaml-frontmatter' | | _Optional_. See [format](#extension-and-format) below |
| frontmatter_delimiter | string<br />\| [string, string] | | _Optional_. See [frontmatter_delimiter](#frontmatter_delimiter) below |
| slug | string | | _Optional_. See [slug](#slug) below |
| fields (required) | Field | | _Optional_. See [fields](#fields) below. Ignored if [Files Collection](/docs/collection-types#file-collections) |
| editor | EditorConfig | | _Optional_. See [editor](#editor) below |
| summary | string | | _Optional_. See [summary](#summary) below |
| summary_fields | list of strings | ['summary'] | _Optional_. A list of fields to show in the table view |
| sortable_fields | SortableFields | | _Optional_. See [sortable_fields](#sortable_fields) below |
| view_filters | ViewFilter | | _Optional_. See [view_filters](#view_filters) below |
| view_groups | ViewGroup | | _Optional_. See [view_groups](#view_groups) below |
## `identifier_field`
@ -192,7 +193,7 @@ editor: {
## `summary`
This setting allows the customization of the collection list view. Similar to the `slug` field, a string with templates can be used to include values of different fields, e.g. `{{title}}`. This option over-rides the default of `title` field and `identifier_field`.
This setting allows the customization of the collection table view. Similar to the `slug` field, a string with templates can be used to include values of different fields, e.g. `{{title}}`. This option over-rides the default of `title` field and `identifier_field`.
**Available Template Tags**

41
packages/docs/content/docs/custom-previews.mdx
View File

@ -326,6 +326,22 @@ CMS.registerPreviewTemplate('general', GeneralPreview);
</CodeTabs>
## Editor Preview Styles
Register a custom stylesheet to use on the preview pane.
```js
CMS.registerPreviewStyle(url);
```
### Raw Styles
If you want to provide a raw CSS string instead of a url, you can pass `{ raw: true }` as the second parameter.
```js
CMS.registerPreviewStyle('.main { color: blue; border: 1px solid gree; }', { raw: true });
```
## Collection Card Preview
`registerPreviewCard` allows you to create a card template that overrides the cards displayed in the collection view.
@ -341,7 +357,6 @@ The following parameters will be passed to your `react_component` during render:
| Param | Type | Description |
| ---------- | ---------------------- | ------------------------------------------------------------------------------------------------- |
| viewStyle | 'list'<br />\| 'grid' | The current view style being displayed |
| entry | object | Object with a `data` field that contains the current value of all widgets in the editor |
| 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 |
@ -352,11 +367,11 @@ The following parameters will be passed to your `react_component` during render:
<CodeTabs>
```js
const PostPreviewCard = ({ entry, widgetFor, viewStyle }) => {
const PostPreviewCard = ({ entry, widgetFor }) => {
return h(
'div',
{ style: { width: '100%' } },
viewStyle === 'grid' ? widgetFor('image') : null,
widgetFor('image'),
h(
'div',
{ style: { padding: '16px', width: '100%' } },
@ -375,7 +390,7 @@ const PostPreviewCard = ({ entry, widgetFor, viewStyle }) => {
{
style: {
display: 'flex',
flexDirection: viewStyle === 'grid' ? 'column' : 'row',
flexDirection: 'column',
alignItems: 'baseline',
gap: '8px',
},
@ -411,10 +426,10 @@ CMS.registerPreviewCard('posts', PostPreviewCard);
```jsx
import CMS from '@staticcms/core';
const PostPreviewCard = ({ entry, widgetFor, viewStyle }) => {
const PostPreviewCard = ({ entry, widgetFor }) => {
return (
<div style={{ width: '100%' }}>
{viewStyle === 'grid' ? widgetFor('image') : null}
{widgetFor('image')}
<div style={{ padding: '16px', width: '100%' }}>
<div
style={{
@ -427,7 +442,7 @@ const PostPreviewCard = ({ entry, widgetFor, viewStyle }) => {
<div
style={{
display: 'flex',
flexDirection: viewStyle === 'grid' ? 'column' : 'row',
flexDirection: 'column',
alignItems: 'baseline',
gap: '8px',
}}
@ -471,10 +486,10 @@ interface Post {
body: string;
}
const PostPreviewCard = ({ entry, widgetFor, viewStyle }: TemplatePreviewCardProps<Post>) => {
const PostPreviewCard = ({ entry, widgetFor }: TemplatePreviewCardProps<Post>) => {
return (
<div style={{ width: '100%' }}>
{viewStyle === 'grid' ? widgetFor('image') : null}
{widgetFor('image')}
<div style={{ padding: '16px', width: '100%' }}>
<div
style={{
@ -487,7 +502,7 @@ const PostPreviewCard = ({ entry, widgetFor, viewStyle }: TemplatePreviewCardPro
<div
style={{
display: 'flex',
flexDirection: viewStyle === 'grid' ? 'column' : 'row',
flexDirection: 'column',
alignItems: 'baseline',
gap: '8px',
}}
@ -521,15 +536,11 @@ CMS.registerPreviewTemplate('posts', PostPreview);
</CodeTabs>
##### Table View
![Post Preview Card Table View](/img/preview_card_list.png)
##### Grid View
![Post Preview Card Grid View](/img/preview_card_grid.png)
## Field Preview
## Collection Field Preview
`registerFieldPreview` allows you to create a custom preview for a specific field in the table view for collections.

20
packages/docs/content/docs/custom-widgets.mdx
View File

@ -373,7 +373,11 @@ If you want to use the media library in your custom widget you will need to use
```js
const FileControl = ({ collection, field, value, entry, onChange }) => {
const handleOpenMediaLibrary = useMediaInsert(value, { field, controlID }, onChange);
const handleChange = ({ path }) => {
onChange(path);
};
const handleOpenMediaLibrary = useMediaInsert(value, { collection, field, controlID }, onChange);
const assetSource = useMediaAsset(value, collection, field, entry);
@ -389,7 +393,11 @@ import useMediaAsset from '@staticcms/core/lib/hooks/useMediaAsset';
import useMediaInsert from '@staticcms/core/lib/hooks/useMediaInsert';
const FileControl = ({ collection, field, value, entry, onChange }) => {
const handleOpenMediaLibrary = useMediaInsert(value, { field, controlID }, onChange);
const handleChange = ({ path }) => {
onChange(path);
};
const handleOpenMediaLibrary = useMediaInsert(value, { collection, field, controlID }, handleChange);
const assetSource = useMediaAsset(value, collection, field, entry);
@ -408,7 +416,7 @@ const FileControl = ({ collection, field, value, entry, onChange }) => {
import useMediaAsset from '@staticcms/core/lib/hooks/useMediaAsset';
import useMediaInsert from '@staticcms/core/lib/hooks/useMediaInsert';
import type { WidgetControlProps } from '@staticcms/core/interface';
import type { WidgetControlProps, MediaPath } from '@staticcms/core/interface';
import type { FC } from 'react';
const FileControl: FC<WidgetControlProps<string, MyField>> = ({
@ -418,7 +426,11 @@ const FileControl: FC<WidgetControlProps<string, MyField>> = ({
entry,
onChange,
}) => {
const handleOpenMediaLibrary = useMediaInsert(internalValue, { field, controlID }, onChange);
const handleChange = ({ path }: MediaPath) => {
onChange(path);
};
const handleOpenMediaLibrary = useMediaInsert(internalValue, { collection, field, controlID }, onChange);
const assetSource = useMediaAsset(value, collection, field, entry);

200
packages/docs/content/docs/migration-guide-v2.mdx Normal file
View File

@ -0,0 +1,200 @@
---
group: Migration
title: How to Upgrade to v2
weight: 101
---
<Alert severity="warning">This guide is a work in progress and subject to change before the final `v2.0.0` release.</Alert>
Static CMS v2 introduces a brand new UI and an updated media library. In this guide, we will walk you through the steps for upgrading to Static CMS v2.
Please [report any issues](https://github.com/StaticJsCMS/static-cms/issues/new) you encounter while upgrading to Static CMS v2.
## Installing
To install the latest version of Static CMS:
```bash
npm install @staticcms/core@^2.0.0-beta.1
```
Or if you’re using yarn:
```bash
yarn add @staticcms/core@^2.0.0-beta.1
```
If you are using a CDN to load Static CMS, simply change your URL:
```html
<script src="https://unpkg.com/@staticcms/app@^2.0.0-beta.1/dist/static-cms-app.js"></script>
```
## Deprecated Items Removed
All previously deprecated items have been removed as part of this release.
- `getAsset` - Use `useMediaAsset` React hook instead
- `createReactClass` - Use [react functional components](https://react.dev/learn) instead
- `isFieldDuplicate` - Use `duplicate` variable instead
- `isFieldHidden` - Use `hidden` variable instead
## Importing Static CMS Styles
In `v2.0.0` the apps stylings are not longer bundled into the main javscript file. For both CDN and bundled setups, you will need to include the css file yourself.
**CDN**:
```html
<link rel="stylesheet" hef="https://unpkg.com/@staticcms/app@^2.0.0-beta.1/dist/main.css" />
```
**Bundling**:
```js
import '@staticcms/core/dist/main.css';
```
### Custom Preview Styles
Some basic preview styles are now provided in order to properly support dark mode and make the basic previews look a bit better. However, if you [provide your own preview styles](/docs/custom-previews#editor-preview-styles) these default styles will not be included in the preview.
## Nested Collections
While still in beta, [Nested Collections](/docs/collection-types#nested-collections) are now fully working and supported in `v2.0.0`. However there are some breaking config changes. The `meta` config has been dropped and its `path` property has been moved into the `nested` prop. You can also no longer specify the widget type for the path.
**Old Config**
<CodeTabs>
```yaml
collections:
- name: pages
label: Pages
label_singular: 'Page'
folder: content/pages
create: true
nested:
depth: 100
summary: '{{title}}'
fields:
- label: Title
name: title
widget: string
- label: Body
name: body
widget: markdown
meta: { path: { widget: string, label: 'Path', index_file: 'index' } }
```
```js
{
collections: [
{
name: 'pages',
label: 'Pages',
label_singular: 'Page',
folder: 'content/pages',
create: true,
nested: {
depth: 100,
summary: '{{title}}',
},
fields: [
{
label: 'Title',
name: 'title',
widget: 'string',
},
{
label: 'Body',
name: 'body',
widget: 'markdown',
},
],
meta: {
path: {
widget: 'string',
label: 'Path',
index_file: 'index',
},
},
},
];
}
```
</CodeTabs>
**New Config**
<CodeTabs>
```yaml
collections:
- name: pages
label: Pages
label_singular: 'Page'
folder: content/pages
create: true
nested:
depth: 100
summary: '{{title}}'
path: { label: 'Path', index_file: 'index' }
fields:
- label: Title
name: title
widget: string
- label: Body
name: body
widget: markdown
```
```js
{
collections: [
{
name: 'pages',
label: 'Pages',
label_singular: 'Page',
folder: 'content/pages',
create: true,
nested: {
depth: 100,
summary: '{{title}}',
path: {
label: 'Path',
index_file: 'index',
},
},
fields: [
{
label: 'Title',
name: 'title',
widget: 'string',
},
{
label: 'Body',
name: 'body',
widget: 'markdown',
},
],
},
];
}
```
</CodeTabs>
## Other Breaking Changes
- [Card previews](/docs/custom-previews#collection-card-preview) now are only used for the card view. The `viewStyle` has been removed. [Field previews](/docs/custom-previews#field-preview) can be used to change the table view.
- Widget Control component property changes:
- `isDisabled` renamed to `disabled`
- `isDuplicate` renamed to `duplicate`
- `isHidden` renamed to `hidden`
- `mediaPaths` is now object of id mapped to an object containing the `path` and optional `alt`
- `useMediaInsert` hook now requires a collection to be passed in. Its callback function now receives an object containing the `path` and optional `alt` instead of a string.
## Other Changes
- `summary_fields` property added to [collection configuration](/docs/collection-overview) to allow customization of the table view. This works with the new [field preview](/docs/custom-previews).
- New widget control property: `forSingleList`. It specifies if the widget is within a singleton `list` widget (string array, number array, etc)