Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Update Retail React App Page Designer integration README #1041

Merged
merged 4 commits into from
Mar 8, 2023
Merged

Update Retail React App Page Designer integration README #1041

Changes from 2 commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
56b77e4
Tweaks to PD README
johnboxall Mar 7, 2023
830f8c6
...
johnboxall Mar 7, 2023
9f65312
Apply suggestions from code review
johnboxall Mar 8, 2023
e00d49e
Merge branch 'develop' into pd-example-tweaks
johnboxall Mar 8, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
86 changes: 44 additions & 42 deletions packages/template-retail-react-app/app/page-designer/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,31 +1,31 @@
____ ____ _
____ ____ _
/ __ \____ _____ ____ / __ \___ _____(_)___ _____ ___ _____
/ /_/ / __ `/ __ `/ _ \ / / / / _ \/ ___/ / __ `/ __ \/ _ \/ ___/
/ ____/ /_/ / /_/ / __/ / /_/ / __(__ ) / /_/ / / / / __/ /
/_/ \__,_/\__, /\___/ /_____/\___/____/_/\__, /_/ /_/\___/_/
/____/ /____/
/ ____/ /_/ / /_/ / __/ / /_/ / __(__ ) / /_/ / / / / __/ /
/_/ \__,_/\__, /\___/ /_____/\___/____/_/\__, /_/ /_/\___/_/
/____/ /____/

---

## Summary
This folder contains React components and utilities that render pages from [Page Designer](https://documentation.b2c.commercecloud.salesforce.com/DOC2/topic/com.demandware.dochelp/content/b2c_commerce/topics/page_designer/b2c_creating_pd_pages.html).

This folder contains the React components and utilities required to render `pages` created in the Business Managers **Page Desginer** backend in your PWA-Kit app. This is a living folder where you, the developer, can add your own component implementations for those that exist in the **Page Designer** backend, or custom components you may have added via an SFRA cartirdge. We have given you a head start by providing some of the components for layout and visualization (e.g. images, grids, and carousels).
It is living folder where you add React.js components responsible for rendering Page Designer components that have been serialized to JSON.
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Did you mean to say "It is a living" ..

Is "It" page designer? or the page designer folder?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't think "living folder" translates well to other cultures.

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I agree. But I don't have any suggestions for alternative 🤷. We could be more direct and say something along the lines of "this is where you'll place all your page designer components that you develop"

johnboxall marked this conversation as resolved.
Show resolved Hide resolved

## Folders
It includes components for layout and visualization of images, grids and and carousels.
johnboxall marked this conversation as resolved.
Show resolved Hide resolved

The `Page Desginer` folder is broken down into 3 main sub-folders:
**By default, Page Designer integration is not enabled in the Retail React App.**
Copy link
Contributor

@rsexton404 rsexton404 Mar 7, 2023 •
edited

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We should link to instructions on how to enable the integration.


- **/core** - Contains the _Page_, _Region_, and _Component_ base assets. Think of these as the basic building blocks for rendering your page. You will not spend a lot of time in this folder, but you will definately be using the _Page_ component, as it's the primary component used to render your experience. The other components will also be useful when you are creating new _assets_.
## Folder Structure

- **/assets** - This folder contains the non-visual components that you dragged and dropped on your **Page Designer** pages. These include things like "Image", "ImageWithText" and and any other Page Designer assets you want to visualize in your PWA-Kit app. If you need to visualize a new component that we haven't provided, you can add it here.

- **/layouts** - Contrary to the above, this folder contains only components that involve layout of other components. We have gotten you off to a good start by giving you various _grid_ and _carousel_ layout components.
- **`/core`** - Base components for rendering: `<Page>`, `<Region>`, and `<Component>`. You shouldn't need to modify them, but will use `<Page>` to render Page Designer content. The other components are useful when you are creating new assets.
johnboxall marked this conversation as resolved.
Show resolved Hide resolved
- **`/assets`** - Non-visual components used in Page Designer. Includes `<Image>` and `<ImageWithText>` as well as other Page Designer assets you want to use in your PWA-Kit app. If you need to visualize a component, you would add it here.
johnboxall marked this conversation as resolved.
Show resolved Hide resolved
- **`/layouts`** - Components responsible for layout. Includes various grids and a `<Carousel>` component.

## Sample Usage

Below is a sample page that you can use as a starting point in your _retail react app_ to visualize pages that have created in business manager. After starting the dev server you can access the page viewer using the following url `http://localhost:3000/page-viewer/homepage-example`. _Note: "homepage-example is a sample page designer page that is included with all Business Manager backends, if you want to view another page you created, please use that id instead._
First, create a new file, `app/pages/page-viewer/index.jsx`, and add the following:
johnboxall marked this conversation as resolved.
Show resolved Hide resolved

```
```jsx
// app/pages/page-viewer/index.jsx

import React from 'react'
Expand All @@ -42,38 +42,38 @@ import {
MobileGrid3r2c
} from '../../page-designer/layouts'

const PageViewer = ({page}) => {
// Assign the components to be rendered for any given page designer component type.
const components = {
'commerce_assets.photoTile': ImageTile,
'commerce_assets.imageAndText': ImageWithText,
'commerce_layouts.carousel': Carousel,
'commerce_layouts.mobileGrid1r1c': MobileGrid1r1c,
'commerce_layouts.mobileGrid2r1c': MobileGrid2r1c,
'commerce_layouts.mobileGrid2r2c': MobileGrid2r2c,
'commerce_layouts.mobileGrid2r3c': MobileGrid2r3c,
'commerce_layouts.mobileGrid3r1c': MobileGrid3r1c,
'commerce_layouts.mobileGrid3r2c': MobileGrid3r2c
}

return (
<Box layerStyle={'page'}>
<Page page={page} components={components} />
</Box>
)
import {HTTPError, HTTPNotFound} from 'pwa-kit-react-sdk/ssr/universal/errors'

const PAGEDESIGNER_TO_COMPONENT = {
'commerce_assets.photoTile': ImageTile,
'commerce_assets.imageAndText': ImageWithText,
'commerce_layouts.carousel': Carousel,
'commerce_layouts.mobileGrid1r1c': MobileGrid1r1c,
'commerce_layouts.mobileGrid2r1c': MobileGrid2r1c,
'commerce_layouts.mobileGrid2r2c': MobileGrid2r2c,
'commerce_layouts.mobileGrid2r3c': MobileGrid2r3c,
'commerce_layouts.mobileGrid3r1c': MobileGrid3r1c,
'commerce_layouts.mobileGrid3r2c': MobileGrid3r2c
}

const PageViewer = ({page}) => (
<Box layerStyle={'page'}>
<Page page={page} components={PAGEDESIGNER_TO_COMPONENT} />
</Box>
)

PageViewer.getProps = async ({api, params}) => {
const {pageId} = params

// Note: There is no error and 404 handling in this example, if you chose to use this code you will have to add that on your own.
const page = await api.shopperExperience.getPage({
parameters: {pageId}
})

return {
page
if (page.isError) {
let ErrorClass = page.type?.endsWith('page-not-found') ? HTTPNotFound : HTTPError
throw new ErrorClass(page.detail)
}

return {page}
}

PageViewer.displayName = 'PageViewer'
Expand All @@ -85,18 +85,20 @@ PageViewer.propTypes = {
export default PageViewer
```

_**Note:** To ensure that this page is routeable you need to add it to your applications routes file._
Second, modify `app/routes.jsx`, adding a route for `<PageViewer>`:
johnboxall marked this conversation as resolved.
Show resolved Hide resolved

```
```diff
// app/routes.jsx

// Create new loadabled page for the `page-viewer`
// Create a loadable page for `page-viewer`.
+ const PageViewer = loadable(() => import('./pages/page-viewer'), {fallback})


// Add the new route object to the routes array
// Add a route.
+ {
+ path: '/page-viewer/:pageId',
+ component: PageViewer
+ },
```
```

Using the local development server, you can now see Page Designer pages rendered in React.js at `http://localhost:3000/page-viewer/:pageid` by providing their `pageid`.