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
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
10 changed files with 359 additions and 114 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

23
BREAKING_CHANGES.md
View File

@ -1,23 +0,0 @@
BREAKING_CHANGES
- Card preview only is used for card view (viewStyle prop removed, theme prop added). Field preview can be used in table view.
- Deprecated stuff removed (getAsset, createReactClass, isFieldDuplicate, isFieldHidden)
- widget prop `isDisabled` renamed to `disabled`
- widget prop `isDuplicate` renamed to `duplicate`
- widget prop `isHidden` renamed to `hidden`
- useMediaInsert now requires collection to be passed
- media path changed from `string | string[]` to `{ path: string | string[], alt?: string }`
- Nested collections, meta config moved into nested config.
CHANGES
- Default styles are now provided in the preview frame. If you provide your own via `registerPreviewStyle`, then these default styles will not be included.
ADDED
- `forSingleList` - Allows for changing styles for single list items
TODO
- Docs on table columns
- Docs on field previews
- Re-add collection description OR document as breaking change

2
packages/core/test/data/widgets.mock.ts
View File

@ -19,8 +19,6 @@ export const createMockWidgetControlProps = <
| 'field'
| 'data'
| 'hasErrors'
| 'isFieldDuplicate'
| 'isFieldHidden'
| 'onChange'
| 'clearMediaControl'
| 'openMediaLibrary'

117
packages/demo/src/cms.jsx
View File

@ -18,48 +18,81 @@ const PostPreview = ({ entry, widgetFor }) => {
);
};
const PostPreviewCard = ({ entry, widgetFor, viewStyle }) => {
return (
<div style={{ width: "100%" }}>
{viewStyle === "grid" ? widgetFor("image") : null}
<div style={{ padding: "16px", width: "100%" }}>
<div
style={{
display: "flex",
width: "100%",
justifyContent: "space-between",
alignItems: "start",
}}
>
<div
style={{
display: "flex",
flexDirection: viewStyle === "grid" ? "column" : "row",
alignItems: "baseline",
gap: "8px",
}}
>
<strong style={{ fontSize: "24px" }}>{entry.data.title}</strong>
<span style={{ fontSize: "16px" }}>{entry.data.date}</span>
</div>
<div
style={{
backgroundColor: entry.data.draft === true ? "blue" : "green",
color: "white",
border: "none",
padding: "4px 8px",
textAlign: "center",
textDecoration: "none",
display: "inline-block",
cursor: "pointer",
borderRadius: "4px",
}}
>
{entry.data.draft === true ? "Draft" : "Published"}
</div>
</div>
</div>
</div>
const PostPreviewCard = ({ entry, theme }) => {
const date = new Date(entry.data.date);
const month = date.getMonth() + 1;
const day = date.getDate();
return h(
'div',
{ style: { width: '100%' } },
h(
'div',
{ style: { padding: '16px', width: '100%' } },
h(
'div',
{
style: {
display: 'flex',
width: '100%',
justifyContent: 'space-between',
alignItems: 'start',
gap: '4px',
color: theme === 'dark' ? 'white' : 'inherit',
},
},
h(
'div',
{
style: {
display: 'flex',
flexDirection: 'column',
alignItems: 'baseline',
gap: '4px',
},
},
h(
'div',
{
style: {
fontSize: '14px',
fontWeight: 700,
color: 'rgb(107, 114, 128)',
fontSize: '14px',
lineHeight: '18px',
},
},
entry.data.title,
),
h(
'span',
{ style: { fontSize: '14px' } },
`${date.getFullYear()}-${month < 10 ? `0${month}` : month}-${
day < 10 ? `0${day}` : day
}`,
),
),
h(
'div',
{
style: {
backgroundColor: entry.data.draft === true ? 'blue' : 'green',
color: 'white',
border: 'none',
padding: '2px 6px',
textAlign: 'center',
textDecoration: 'none',
display: 'inline-block',
cursor: 'pointer',
borderRadius: '4px',
fontSize: '14px',
},
},
entry.data.draft === true ? 'Draft' : 'Published',
),
),
),
);
};

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)

11
packages/docs/src/components/docs/DocsContent.tsx
View File

@ -32,7 +32,7 @@ const DocsContent = styled('div')(
& p:not(:first-of-type) {
margin-top: 8px;
}
& pre + p:not(:first-of-type) {
margin-top: 20px;
}
@ -174,6 +174,15 @@ const DocsContent = styled('div')(
padding: 1rem;
overflow: auto;
margin: 0;
border-radius: 12px;
}
.dark & pre.code-tabpanel,
.dark & pre.code-tabpanel[class*='language-'],
.light & pre.code-tabpanel,
.light & pre.code-tabpanel[class*='language-'] {
border-top-left-radius: 0;
border-top-right-radius: 0;
}
& pre code {

2
packages/docs/src/components/docs/components/CodeTabs.tsx
View File

@ -142,7 +142,7 @@ const CodeTabs = ({ children }: CodeTabsProps) => {
</Box>
{tabs.map((tabData, index) => (
<TabPanel key={tabData.className} value={value} index={index}>
<pre className={tabData.className}>
<pre className={`code-tabpanel ${tabData.className}`} tabIndex={0}>
<code
className={tabData.className}
dangerouslySetInnerHTML={{ __html: tabData.content }}

8
packages/docs/src/components/docs/table_of_contents/DocsTableOfContents.tsx
View File

@ -18,7 +18,11 @@ const getNestedHeadings = (headingElements: HTMLHeadingElement[]) => {
const nestedHeadings: NestedHeading[] = [];
headingElements.forEach(heading => {
const { innerText: title, id } = heading;
const { innerText, id } = heading;
const title = innerText
.replace(/\n/g, '')
.replace(/Beta Feature$/g, '')
.trim();
if (heading.nodeName === 'H1' || heading.nodeName === 'H2') {
nestedHeadings.push({ id, title, items: [] });
@ -118,7 +122,7 @@ const StyledNav = styled('nav')(
max-height: calc(100vh - 72px);
overflow-y: auto;
top: 16px;
${theme.breakpoints.between('md', 'lg')} {
top: 24px;
}