Skip to content

Commit c18c529

Browse files
yavorskyavorsk
committed
add upgrade guide entry
1 parent dbe3473 commit c18c529

File tree

1 file changed

+171
-143
lines changed

1 file changed

+171
-143
lines changed

‎docs/upgrades/unreleased.md

+171-143
Original file line numberDiff line numberDiff line change
@@ -1,179 +1,207 @@
11
## Unreleased
22

3-
* If you are importing any _editing_ utils from `@sitecore-jss/sitecore-jss/utils` in your code, please update the import path to `@sitecore-jss/sitecore-jss/editing`. For now these exports are still available in the old path and marked as deprecated. They will be removed in the next major version release. Specifically for the following utils:
4-
* ExperienceEditor
5-
* HorizonEditor
6-
* isEditorActive
7-
* resetEditorChromes
8-
* handleEditorAnchors
9-
* Metadata
10-
* DefaultEditFrameButton
11-
* DefaultEditFrameButtons
12-
* DefaultEditFrameButtonIds
13-
* EditFrameDataSource
14-
* ChromeCommand
15-
* FieldEditButton
16-
* WebEditButton
17-
* EditButtonTypes
18-
* mapButtonToCommand
3+
- If you are importing any _editing_ utils from `@sitecore-jss/sitecore-jss/utils` in your code, please update the import path to `@sitecore-jss/sitecore-jss/editing`. For now these exports are still available in the old path and marked as deprecated. They will be removed in the next major version release. Specifically for the following utils:
4+
- ExperienceEditor
5+
- HorizonEditor
6+
- isEditorActive
7+
- resetEditorChromes
8+
- handleEditorAnchors
9+
- Metadata
10+
- DefaultEditFrameButton
11+
- DefaultEditFrameButtons
12+
- DefaultEditFrameButtonIds
13+
- EditFrameDataSource
14+
- ChromeCommand
15+
- FieldEditButton
16+
- WebEditButton
17+
- EditButtonTypes
18+
- mapButtonToCommand
1919

2020
# react
2121

22-
* With the simplification of Editing Support work we have added the following breaking changes to the `sitecore-jss-react` package. Please make the necessary updates.
22+
- With the simplification of Editing Support work we have added the following breaking changes to the `sitecore-jss-react` package. Please make the necessary updates.
2323
- `ComponentConsumerProps` is removed. You might need to reuse _WithSitecoreContextProps_ type.
2424

2525
### headless-ssr-experience-edge
26-
* Replace `scripts/generate-config.js` if you have not modified it. Otherwise:
27-
* Add a `trim()` call to `config[prop]` and replace comma before a newline (`,`) with semicolon (`;`) in configText prop assignment so it would look like this:
2826

29-
```ts
30-
configText += `config.${prop} = process.env.REACT_APP_${constantCase(prop)} || "${
31-
config[prop]?.trim()
32-
}";\n`;
33-
```
27+
- Replace `scripts/generate-config.js` if you have not modified it. Otherwise:
3428

35-
# angular
36-
37-
* Update Angular and core dependencies to ~17.3.1, related dependencies
38-
39-
* Update Typescript to ~5.2.2
40-
41-
* Replace `scripts/generate-config.ts` if you have not modified it. Otherwise:
42-
* Add a `trim()` call to `config[prop]` (use toString() to avoid type conflicts) and replace commas before a newline (`,`) with semicolon (`;`) in configText prop assignments so it would look like this:
43-
44-
```ts
45-
configText += `config.${prop} = process.env.${constantCase(prop)} || "${config[prop]?.toString().trim()}";\n`;
46-
```
47-
48-
* Update import in _src/templates/angular/server.bundle.ts_
49-
Use _'zone.js'_ instead of _'zone.js/dist/zone-node'_
50-
51-
```ts
52-
import 'zone.js';
53-
```
54-
* Update import in _src/templates/angular/src/polyfills.ts_
55-
Use _'zone.js'_ instead of _'zone.js/dist/zone-node'_
29+
- Add a `trim()` call to `config[prop]` and replace comma before a newline (`,`) with semicolon (`;`) in configText prop assignment so it would look like this:
5630

57-
```ts
58-
import 'zone.js';
59-
```
60-
61-
# vue
62-
63-
* Replace `scripts/generate-config.js` if you have not modified it. Otherwise:
64-
* Add a `trim()` call to `config[prop]` and replace commas before a newline (`,`) with semicolon (`;`) in configText prop assignments so it would look like this:
31+
```ts
32+
configText += `config.${prop} = process.env.REACT_APP_${constantCase(prop)} || "${config[
33+
prop
34+
]?.trim()}";\n`;
35+
```
6536

66-
```ts
67-
configText += `config.${prop} = process.env.VUE_APP_${constantCase(prop)} || "${
68-
config[prop]?.trim()
69-
}";\n`;
70-
```
37+
# angular
7138

72-
# nextjs
39+
- Update Angular and core dependencies to ~17.3.1, related dependencies
7340

74-
* Replace `scripts/generate-config.ts` if you have not modified it. Otherwise:
75-
* Add a `trim()` call to `config[prop]` and replace comma before a newline (`,`) with semicolon (`;`) in configText prop assignment so it would look like this:
41+
- Update Typescript to ~5.2.2
7642

77-
```ts
78-
configText += `config.${prop} = process.env.${constantCase(prop)} || '${config[prop]?.trim()}';\n`;
79-
```
43+
- Replace `scripts/generate-config.ts` if you have not modified it. Otherwise:
8044

81-
* Remove cors header for API endpoints from _lib/next-config/plugins/cors-header_ plugin since cors is handled by API handlers / middlewares:
45+
- Add a `trim()` call to `config[prop]` (use toString() to avoid type conflicts) and replace commas before a newline (`,`) with semicolon (`;`) in configText prop assignments so it would look like this:
8246

8347
```ts
84-
{
85-
source: '/api/:path*',
86-
headers: [
87-
{
88-
key: 'Access-Control-Allow-Origin',
89-
value: config.sitecoreApiHost.replace(/\/$/, ''),
90-
},
91-
],
92-
},
48+
configText += `config.${prop} = process.env.${constantCase(prop)} || "${config[prop]
49+
?.toString()
50+
.trim()}";\n`;
9351
```
9452

95-
* Update _pages/api/editing/render.ts_ API handler initialization signature, since _resolvePageUrl_ function now accepts an object and _serverUrl_ now is optional, it's ommited when Pages Metadata Edit Mode is used. Update the handler initialization as follows:
53+
- Update import in _src/templates/angular/server.bundle.ts_
54+
Use _'zone.js'_ instead of _'zone.js/dist/zone-node'_
9655

97-
```ts
98-
const handler = new EditingRenderMiddleware({
99-
resolvePageUrl: ({ serverUrl, itemPath }) => `${serverUrl}${itemPath}`,
100-
}).getHandler();
101-
```
56+
```ts
57+
import 'zone.js';
58+
```
10259

103-
* The implementation of 'EditingComponentPlaceholder' has been removed. Its purpose to avoid refreshing the entire page during component editing in Pages had never been fully utilized. The references to it and to `RenderingType` enum in `[[...path]].tsx` of the nextjs app (and in any custom code) should be removed:
60+
- Update import in _src/templates/angular/src/polyfills.ts_
61+
Use _'zone.js'_ instead of _'zone.js/dist/zone-node'_
10462

105-
```ts
106-
import Layout from 'src/Layout';
107-
import { RenderingType, EditingComponentPlaceholder } from '@sitecore-jss/sitecore-jss-nextjs';
108-
...
109-
const isComponentRendering =
110-
layoutData.sitecore.context.renderingType === RenderingType.Component;
111-
...
112-
{isComponentRendering ? (
113-
<EditingComponentPlaceholder rendering={layoutData.sitecore.route} />
114-
) : (
115-
<Layout layoutData={layoutData} headLinks={headLinks} />
116-
)}
117-
...
118-
```
63+
```ts
64+
import 'zone.js';
65+
```
11966

120-
# nextjs-xmcloud
67+
# vue
68+
69+
- Replace `scripts/generate-config.js` if you have not modified it. Otherwise:
12170

122-
* Render a new `EditingScripts` component in your `Scripts.ts` file to support a new Editing Integration feature.
71+
- Add a `trim()` call to `config[prop]` and replace commas before a newline (`,`) with semicolon (`;`) in configText prop assignments so it would look like this:
12372

12473
```ts
125-
import { EditingScripts } from '@sitecore-jss/sitecore-jss-nextjs';
126-
...
127-
const Scripts = (): JSX.Element | null => (
128-
<>
129-
<EditingScripts />
130-
...
131-
</>
132-
);
74+
configText += `config.${prop} = process.env.VUE_APP_${constantCase(prop)} || "${config[
75+
prop
76+
]?.trim()}";\n`;
13377
```
13478
135-
* Add a `useSiteQuery` parameter when `GraphQLDictionaryService` is initialized in `/src/lib/dictionary-service-factory.ts` :
136-
```
137-
new GraphQLDictionaryService({
138-
siteName,
139-
clientFactory,
140-
.....
141-
useSiteQuery: true,
142-
})
79+
# nextjs
14380
144-
* We have introduced a new configuration option, `pagesEditMode`, in the `\src\pages\api\editing\config.ts` file to support the new editing metadata architecture for Pages (XMCloud). This option allows you to specify the editing mode used by Pages. It is set to `metadata` by default. However, if you are not ready to use a new integration and continue using the existing architecture, you can explicitly set the `pagesEditMode` to `chromes`.
81+
- Replace `scripts/generate-config.ts` if you have not modified it. Otherwise:
14582
146-
```ts
147-
import { EditMode } from '@sitecore-jss/sitecore-jss-nextjs';
83+
- Add a `trim()` call to `config[prop]` and replace comma before a newline (`,`) with semicolon (`;`) in configText prop assignment so it would look like this:
14884
149-
const handler = new EditingConfigMiddleware({
150-
...
151-
pagesEditMode: EditMode.Chromes,
152-
}).getHandler();
85+
```ts
86+
configText += `config.${prop} = process.env.${constantCase(prop)} || '${config[
87+
prop
88+
]?.trim()}';\n`;
15389
```
15490
155-
* Introduce a new _lib/graphql-editing-service.ts_ file to initialize a _graphQLEditingService_ to support a new Editing Metadata Mode. Can be done by adding this file from the latest version introduced in _nextjs-xmcloud_ base template.
91+
- Remove cors header for API endpoints from _lib/next-config/plugins/cors-header_ plugin since cors is handled by API handlers / middlewares:
92+
93+
```ts
94+
{
95+
source: '/api/:path*',
96+
headers: [
97+
{
98+
key: 'Access-Control-Allow-Origin',
99+
value: config.sitecoreApiHost.replace(/\/$/, ''),
100+
},
101+
],
102+
},
103+
```
104+
105+
- Update _pages/api/editing/render.ts_ API handler initialization signature, since _resolvePageUrl_ function now accepts an object and _serverUrl_ now is optional, it's ommited when Pages Metadata Edit Mode is used. Update the handler initialization as follows:
106+
107+
```ts
108+
const handler = new EditingRenderMiddleware({
109+
resolvePageUrl: ({ serverUrl, itemPath }) => `${serverUrl}${itemPath}`,
110+
}).getHandler();
111+
```
112+
113+
- The implementation of 'EditingComponentPlaceholder' has been removed. Its purpose to avoid refreshing the entire page during component editing in Pages had never been fully utilized. The references to it and to `RenderingType` enum in `[[...path]].tsx` of the nextjs app (and in any custom code) should be removed:
114+
115+
```ts
116+
import Layout from 'src/Layout';
117+
import { RenderingType, EditingComponentPlaceholder } from '@sitecore-jss/sitecore-jss-nextjs';
118+
...
119+
const isComponentRendering =
120+
layoutData.sitecore.context.renderingType === RenderingType.Component;
121+
...
122+
{isComponentRendering ? (
123+
<EditingComponentPlaceholder rendering={layoutData.sitecore.route} />
124+
) : (
125+
<Layout layoutData={layoutData} headLinks={headLinks} />
126+
)}
127+
...
128+
```
156129

157-
* Update _lib/page-props-factory/plugins/preview-mode_ plugin to support a new Editing Metadata Mode. Can be done by replacing this file with the latest version introduced in _nextjs-xmcloud_ base template.
158-
159-
* To support editing for fields in Pages, the new editing metadata architecture relies on the new metadata property 'field.metadata' (instead of on 'field.editable', which won't be used in this scenario). If you are using the new editing arhitecture in Pages (EditMode.Metadata) and have custom field component that manipulates or relies on 'field.editable' in some way, it may need to be reworked. Experience Editor still relies on 'field.editable', so it needs to be supported. See example below from SXA's Banner component:
130+
# nextjs-xmcloud
160131

161-
```ts
162-
import { useSitecoreContext, EditMode } from '@sitecore-jss/sitecore-jss-nextjs';
163-
...
164-
export const Banner = (props: ImageProps): JSX.Element => {
165-
const { sitecoreContext } = useSitecoreContext();
166-
const isMetadataMode = sitecoreContext?.editMode === EditMode.Metadata;
167-
...
168-
const modifyImageProps = !isMetadataMode
169-
? {
170-
...props.fields.Image,
171-
editable: props?.fields?.Image?.editable
172-
?.replace(`width="${props?.fields?.Image?.value?.width}"`, 'width="100%"')
173-
.replace(`height="${props?.fields?.Image?.value?.height}"`, 'height="100%"'),
174-
}
175-
: { ...props.fields.Image };
176-
...
177-
}
178-
...
179-
```
132+
- Render a new `EditingScripts` component in your `Scripts.ts` file to support a new Editing Integration feature.
133+
134+
```ts
135+
import { EditingScripts } from '@sitecore-jss/sitecore-jss-nextjs';
136+
...
137+
const Scripts = (): JSX.Element | null => (
138+
<>
139+
<EditingScripts />
140+
...
141+
</>
142+
);
143+
```
144+
145+
- Add a `useSiteQuery` parameter when `GraphQLDictionaryService` is initialized in `/src/lib/dictionary-service-factory.ts` :
146+
147+
```
148+
new GraphQLDictionaryService({
149+
siteName,
150+
clientFactory,
151+
.....
152+
useSiteQuery: true,
153+
})
154+
155+
```
156+
157+
- We have introduced a new configuration option, `pagesEditMode`, in the `\src\pages\api\editing\config.ts` file to support the new editing metadata architecture for Pages (XMCloud). This option allows you to specify the editing mode used by Pages. It is set to `metadata` by default. However, if you are not ready to use a new integration and continue using the existing architecture, you can explicitly set the `pagesEditMode` to `chromes`.
158+
159+
```ts
160+
import { EditMode } from '@sitecore-jss/sitecore-jss-nextjs';
161+
162+
const handler = new EditingConfigMiddleware({
163+
...
164+
pagesEditMode: EditMode.Chromes,
165+
}).getHandler();
166+
```
167+
168+
- Introduce a new _lib/graphql-editing-service.ts_ file to initialize a _graphQLEditingService_ to support a new Editing Metadata Mode. Can be done by adding this file from the latest version introduced in _nextjs-xmcloud_ base template.
169+
170+
- Update _lib/page-props-factory/plugins/preview-mode_ plugin to support a new Editing Metadata Mode. Can be done by replacing this file with the latest version introduced in _nextjs-xmcloud_ base template.
171+
172+
- To support editing for fields in Pages, the new editing metadata architecture relies on the new metadata property 'field.metadata' (instead of on 'field.editable', which won't be used in this scenario). If you are using the new editing arhitecture in Pages (EditMode.Metadata) and have custom field component that manipulates or relies on 'field.editable' in some way, it may need to be reworked. Experience Editor still relies on 'field.editable', so it needs to be supported. See example below from SXA's Banner component:
173+
174+
```ts
175+
import { useSitecoreContext, EditMode } from '@sitecore-jss/sitecore-jss-nextjs';
176+
...
177+
export const Banner = (props: ImageProps): JSX.Element => {
178+
const { sitecoreContext } = useSitecoreContext();
179+
const isMetadataMode = sitecoreContext?.editMode === EditMode.Metadata;
180+
...
181+
const modifyImageProps = !isMetadataMode
182+
? {
183+
...props.fields.Image,
184+
editable: props?.fields?.Image?.editable
185+
?.replace(`width="${props?.fields?.Image?.value?.width}"`, 'width="100%"')
186+
.replace(`height="${props?.fields?.Image?.value?.height}"`, 'height="100%"'),
187+
}
188+
: { ...props.fields.Image };
189+
...
190+
}
191+
...
192+
```
193+
194+
- Jss now supports component level personalization for XM Cloud. See below code from personalize.ts. _personalizeData_ contains _componentVariantIds_ property which has the personalized components. It can be passed to the _personalizeLayout_ function to apply the personalization to the _layoutData_:
195+
196+
```ts
197+
// Get variant(s) for personalization (from path)
198+
const personalizeData = getPersonalizedRewriteData(path);
199+
200+
// Modify layoutData to use specific variant(s) instead of default
201+
// This will also set the variantId on the Sitecore context so that it is accessible here
202+
personalizeLayout(
203+
props.layoutData,
204+
personalizeData.variantId,
205+
personalizeData.componentVariantIds
206+
);
207+
```

0 commit comments

Comments
 (0)