215 lines
7.0 KiB
Plaintext
215 lines
7.0 KiB
Plaintext
---
|
||
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)
|
||
|
||
## Deprecations
|
||
|
||
In the Widget Control component property, the following properties have been deprecated. They will be removed in `v3.0.0`.
|
||
|
||
| Param | Type | Description |
|
||
| ------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||
| mediaPaths | object | <Deprecated>Use [useMediaInsert](/docs/custom-widgets#interacting-with-the-media-library) instead.</Deprecated> Key/value object of control IDs (passed to the media library) mapping to media paths |
|
||
| clearMediaControl | function | <Deprecated>Use [useMediaInsert](/docs/custom-widgets#interacting-with-the-media-library) instead.</Deprecated> Clears a control ID's value from the internal store |
|
||
| openMediaLibrary | function | <Deprecated>Use [useMediaInsert](/docs/custom-widgets#interacting-with-the-media-library) instead.</Deprecated> Opens the media library popup. See [Open Media Library](#open-media-library) |
|
||
| removeInsertedMedia | function | <Deprecated>Use [useMediaInsert](/docs/custom-widgets#interacting-with-the-media-library) instead.</Deprecated> Removes draft media for a give control ID |
|
||
| removeMediaControl | function | <Deprecated>Use [useMediaInsert](/docs/custom-widgets#interacting-with-the-media-library) instead.</Deprecated> Clears a control ID completely from the internal store |
|