[feature] V2 Migration Guide

[cjwiseman11]

Is your feature request related to a problem? Please describe.
We would like to migrate to the latest version of this package (2.x.x) but there is no migration guide and we can't find any examples of how to use the new components with "composition" and move away from class inheritance .

Describe the solution you'd like
A V1 to V2 migration guide or some clear examples of how to use features such as Page and ResponsiveGrid

Describe alternatives you've considered
We have trawled through changelogs, release logs, PRs and unit tests but it is still not clear how to migrate from V1 effectively

Additional context
As a direct example, how would we pass the author components down, like we do for class components with "this.childComponents"

class GenericCmsPage extends Page {
  render() {
   ...
     {this.childComponents}
   ...
  }
}

[sharanyavinod]

@maximilianvoss @gabrielwalt FYI

[cjwiseman11]

Heya. Any updates on this?

Another query we have is: is there a way to disable the placeholder for certain components in the new world?

[mkovacek]

Would be really useful to have such examples.
If there is no docs at the moment, some code example would be enough

[agustinlburgosglb]

Any updates on this?

[jwolfe890]

Doesn't seem like a guide is coming anytime soon. Has anyone been successful with extending Page in version 2.0? I'm running into the same issue of OP after upgrade.

[cjwiseman11]

Hey @jwolfe890

We have successfully upgraded to V2 but it was a lot of trial and error. We were given this NextJS example but we didn't find it too useful as it was not using Typescript and the examples are very basic: https://github.com/adobe/aem-nextjs-template.

In the example I originally posted, the code would change to

const GenericCmsPage = (props) => {
  return (
   ...
     <Page {...props} />
   ...
  )
}

Props being AEM data, childComponents etc.

Each component also needs to be wrapped with EditableComponent where the config is passed (instead of passing the config to MapTo previously)

        <EditableComponent config={config}>
          <Component {...props} />
        </EditableComponent>

There is a bit of info on it here: https://github.com/adobe/aem-react-editable-components/tree/master/src/components

And some documentation here: https://experienceleague.adobe.com/docs/experience-manager-learn/getting-started-with-aem-headless/spa-editor/how-to/react-core-components-v2.html?lang=en

It has been a while since we worked on this is off the top of my head but let me know if you have any other questions and maybe I can answer or point in the right direction.

[jwolfe890]

Hey Chris, Thanks for your response! I was able to stumble through and get components rendering from that approach. I'm noticing that now that after opening a Page, there is an extra placeholder Grid container added. I tried the same approach with ResponsiveGrid in the containers. Did you face any similar issues with the page itself?

…

On Tue, Mar 21, 2023 at 1:02 PM Chris Wiseman ***@***.***> wrote: Hey @jwolfe890 <https://github.com/jwolfe890> We have successfully upgraded to V2 but it was a lot of trial and error. We were given this NextJS example but we didn't find it too useful as it was not using Typescript and the examples are very basic: https://github.com/adobe/aem-nextjs-template. In the example I originally posted, the code would change to const GenericCmsPage = (props) => { return ( ... <Page {...props} /> ... ) } Props being AEM data, childComponents etc. Each component also needs to be wrapped with EditableComponent where the config is passed (instead of passing the config to MapTo previously) <EditableComponent config={config}> <Component {...props} /> </EditableComponent> There is a bit of info on it here: https://github.com/adobe/aem-react-editable-components/tree/master/src/components And some documentation here: https://experienceleague.adobe.com/docs/experience-manager-learn/getting-started-with-aem-headless/spa-editor/how-to/react-core-components-v2.html?lang=en It has been a while since we worked on this is off the top of my head but let me know if you have any other questions and maybe I can answer or point in the right direction. — Reply to this email directly, view it on GitHub <#141 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/ADFLI5E2RCMEUJF6HMP4O6DW5HUKBANCNFSM6AAAAAARUGHBKQ> . You are receiving this because you were mentioned.Message ID: ***@***.***>

[mkovacek]

Hi @cjwiseman11 , @jwolfe890

I have integrated Next.js using the remote spa editor and v2 components.
But the SPA editor is working a bit off, once I create a new page, in edit mode, component placeholders are not showing up -> I need to switch to preview and back to edit mode to be able to edit components.

Another thing is once I add the same component twice in a container / responsive grid, for the first component placeholder is rendered, and for the component, the placeholder doesn't show up -> page reload is needed to get this working.

Did you have similar issues?

This is what AemPage looks like, I can't just pass props, since some of the objects such as cqChildren don't exist in page.model.json

Also, I need to have 2 different types of pages based if I'm rendering nextjs inside AEM author, and different once Next.js is directly used.

export default function AemPage(props) {
    const getPage = () => {
        let page;

        if (isAuthor()) {
            page = (
                <Page cqChildren={props[Constants.CHILDREN_PROP]}
                      cqItems={props[Constants.ITEMS_PROP]}
                      cqItemsOrder={props[Constants.ITEMS_ORDER_PROP]}
                      cqPath={props[Constants.PATH_PROP]}/>
            );
        } else {
            page = (
                <Page cqChildren={props[Constants.CHILDREN_PROP]}
                      cqItems={props[Constants.ITEMS_PROP]}
                      cqItemsOrder={props[Constants.ITEMS_ORDER_PROP]}
                      model={props}
                      pagePath={props[Constants.PATH_PROP]}
                      itemPath={props[Constants.PATH_PROP]}/>
            );
        }

        return page;
    }

    return (
        getPage()
    );
}

More info here #145

[jwolfe890]

Hi @cjwiseman11 , @jwolfe890

I have integrated Next.js using the remote spa editor and v2 components. But the SPA editor is working a bit off, once I create a new page, in edit mode, component placeholders are not showing up -> I need to switch to preview and back to edit mode to be able to edit components.

Another thing is once I add the same component twice in a container / responsive grid, for the first component placeholder is rendered, and for the component, the placeholder doesn't show up -> page reload is needed to get this working.

Did you have similar issues?

This is what AemPage looks like, I can't just pass props, since some of the objects such as cqChildren don't exist in page.model.json

Also, I need to have 2 different types of pages based if I'm rendering nextjs inside AEM author, and different once Next.js is directly used.

export default function AemPage(props) {
    const getPage = () => {
        let page;

        if (isAuthor()) {
            page = (
                <Page cqChildren={props[Constants.CHILDREN_PROP]}
                      cqItems={props[Constants.ITEMS_PROP]}
                      cqItemsOrder={props[Constants.ITEMS_ORDER_PROP]}
                      cqPath={props[Constants.PATH_PROP]}/>
            );
        } else {
            page = (
                <Page cqChildren={props[Constants.CHILDREN_PROP]}
                      cqItems={props[Constants.ITEMS_PROP]}
                      cqItemsOrder={props[Constants.ITEMS_ORDER_PROP]}
                      model={props}
                      pagePath={props[Constants.PATH_PROP]}
                      itemPath={props[Constants.PATH_PROP]}/>
            );
        }

        return page;
    }

    return (
        getPage()
    );
}

More info here #145

Do you use ResponsiveGrid? How are you rendering your containers? I had Page issues, but not in the way you're describing. The component placeholders are appearing fine, I just get an unneeded one. NextJS I imagine is a different animal though.

[mkovacek]

I have responsive grid component in AEM template structure, and by only using React Page component, responsive grid is mapped correctly and rendered in Nextjs.

Do you use responsive grid / container from this aem-react-editable-components, or do you extend it and map it to your AEM component?

[alanjo4]

I have responsive grid component in AEM template structure, and by only using React Page component, responsive grid is mapped correctly and rendered in Nextjs.

Do you use responsive grid / container from this aem-react-editable-components, or do you extend it and map it to your AEM component?

I've the same error here, I've the grid component in aem template structure, but it's not rendering, basically Page component is rendering on Editor Mode, and also on the preview mode, but I'm not able to see the drag and drop placeholder and things from ResponsiveGrid. This is just a question, is it possible that acs-common package is impacting in this issue? or maybe with https://github.com/adobe/aem-core-wcm-components .

[cjwiseman11]

Hey

Apologies for not getting back it has been crazy busy lately. Also it has been a while since I worked on this but hopefully I can try and help with some of the questions.

I'm noticing that now that after opening a
Page, there is an extra placeholder Grid container added. I tried the same
approach with ResponsiveGrid in the containers. Did you face any
similar issues with the page itself?

I'm not sure what you mean by this exactly but basically wherever we had a class extending "ResponsiveGrid" we would refactor to passing the props into <ResponsiveGrid {...props} />

- class CmsAccordion extends ResponsiveGrid 
+ <ResponsiveGrid {...props} />

Any extends Pages would pass props to <Pages {...props} />

(props being the AEM component data)

I need to switch to preview and back to edit mode to be able to edit components.

I believe you need EditableComponent wrapped for the component placeholder?

Our top level looked like this:

      <EditableComponent {...model}>
        <MappedPage
          cqItems={cqItems[Constants.ITEMS_PROP]}
          cqItemsOrder={cqItems[Constants.ITEMS_ORDER_PROP]}
          cqPath={ModelManager.rootPath}
          navigation={navigation}
          pageTitle={pageTitle}
          title={title}
          hideTitle={hideTitle}
          breadcrumbs={breadcrumbs}
        />
      </EditableComponent>

Anything for author has to be wrapped with EditableComponent

I just get an unneeded one

We had some places where we didn't need the additional placeholder.. I believe we fixed it with a prop

isInEditor={showPlaceholder}

To help our migration we created a MapTo wrapper so we could just simply update wherever we used the MapTo function for the author to use our custom EditableComponent wrapper

export default (resourceType: string | string[]) => (Component: any, config?: any) => {
  const WrappedComponent = (props: EditableComponentProps) => {
    return (
      <EditableComponent config={config} {...props}>
        <Component {...props} />
      </EditableComponent>
    );
  };

  MapTo(resourceType)(WrappedComponent as FunctionComponent);
};

[mkovacek]

Our top level looked like this:

      <EditableComponent {...model}>
        <MappedPage
          cqItems={cqItems[Constants.ITEMS_PROP]}
          cqItemsOrder={cqItems[Constants.ITEMS_ORDER_PROP]}
          cqPath={ModelManager.rootPath}
          navigation={navigation}
          pageTitle={pageTitle}
          title={title}
          hideTitle={hideTitle}
          breadcrumbs={breadcrumbs}
        />
      </EditableComponent>

So I have Page react component which is mapped to AEM Page component

import React from 'react';
import {Page, MapTo, EditableComponent} from '@adobe/aem-react-editable-components';

function ContentPage(props) {
    return (
        <EditableComponent {...props}>
            <Page {...props} />
        </EditableComponent>
    )
}

export default MapTo('wknd-spa-nextjs/components/remotepagenext')(ContentPage);

Next.js page which is handling the requests, does SSR and passes the model to the Page component

import React from 'react';
import {Constants} from "@adobe/aem-spa-page-model-manager";
import {getPageModel} from "../utils/SSRUtils";
import {isAuthor} from "../utils/EnvironemntUtils";
import ContentPage from "../components/page/ContentPage";

export default function AemPage(pageModel) {
    const getPage = () => {
        if (isAuthor()) {
            //cqPath is needed, otherwise authoring doesn't work
            return (
                    <ContentPage cqChildren={pageModel[Constants.CHILDREN_PROP]}
                          cqItems={pageModel[Constants.ITEMS_PROP]}
                          cqItemsOrder={pageModel[Constants.ITEMS_ORDER_PROP]}
                          cqPath={pageModel[Constants.PATH_PROP]}
                    />
            );
        } else {
            //todo:
            // cqPath has wrong value when when SSR is enabled
            return (
                    <ContentPage cqChildren={pageModel[Constants.CHILDREN_PROP]}
                          cqItems={pageModel[Constants.ITEMS_PROP]}
                          cqItemsOrder={pageModel[Constants.ITEMS_ORDER_PROP]}
                          model={pageModel}
                          pagePath={pageModel[Constants.PATH_PROP]}
                          itemPath={pageModel[Constants.PATH_PROP]}
                    />
            );
        }
    }

    return (
        getPage()
    );
}


export async function getServerSideProps(context) {
    return await getPageModel(context);
}

@cjwiseman11 I still have funny behavior in the editor. I need to switch from Edit to Preview and back to Edit mode.

Also if in edit mode I drag and drop 2 times some components, 2nd component is not visible (also in the Content tree in sidekick) with a refresh of the page component appearing.

Can you tell me which props should be passed to the Page component from this library? As you can see that I'm having 2 versions (one for author, one for delivery) to get somehow this "working"

[Leela-Pavan-Kumar]

Hey Chris, Thanks for your response! I was able to stumble through and get components rendering from that approach. I'm noticing that now that after opening a Page, there is an extra placeholder Grid container added. I tried the same approach with ResponsiveGrid in the containers. Did you face any similar issues with the page itself?
…
On Tue, Mar 21, 2023 at 1:02 PM Chris Wiseman @.> wrote: Hey @jwolfe890 https://github.com/jwolfe890 We have successfully upgraded to V2 but it was a lot of trial and error. We were given this NextJS example but we didn't find it too useful as it was not using Typescript and the examples are very basic: https://github.com/adobe/aem-nextjs-template. In the example I originally posted, the code would change to const GenericCmsPage = (props) => { return ( ... <Page {...props} /> ... ) } Props being AEM data, childComponents etc. Each component also needs to be wrapped with EditableComponent where the config is passed (instead of passing the config to MapTo previously) <Component {...props} /> There is a bit of info on it here: https://github.com/adobe/aem-react-editable-components/tree/master/src/components And some documentation here: https://experienceleague.adobe.com/docs/experience-manager-learn/getting-started-with-aem-headless/spa-editor/how-to/react-core-components-v2.html?lang=en It has been a while since we worked on this is off the top of my head but let me know if you have any other questions and maybe I can answer or point in the right direction. — Reply to this email directly, view it on GitHub <#141 (comment)>, or unsubscribe https://github.com/notifications/unsubscribe-auth/ADFLI5E2RCMEUJF6HMP4O6DW5HUKBANCNFSM6AAAAAARUGHBKQ . You are receiving this because you were mentioned.Message ID: @.>

Hey John,

Were you able to resolve this issue? I too have similar issue after upgrading to V2.

Please let me know the approach you followed to avoid the duplicate placholder on page.