Merge pull request #2410 from strapi/user/side-editor-preview-beta

Preview: Side panel

Author: meganelacheny

docusaurus/docs/dev-docs/preview.md

@@ -19,9 +19,11 @@ The present page describes how to set up the Preview feature in Strapi. Once set
 
   ```bash
   CLIENT_URL=https://your-frontend-app.com
-  PREVIEW_SECRET=your-secret-key # optional, required with Next.js draft mode
+  PREVIEW_SECRET=your-secret-key
   ```
 
+  The `PREVIEW_SECRET` key is optional but required with Next.js draft mode.
+
 * A front-end application for your Strapi project should be already created and set up.
 :::
 
@@ -78,7 +80,7 @@ preview: {
 // …
 ```
 
-An example of [URL generation logic](#2-add-url-generation-logic) in given in the following basic implementation guide.
+An example of [URL generation logic](#2-add-url-generation) in given in the following basic implementation guide.
 
 #### Previewing draft entries
 
@@ -101,13 +103,15 @@ async handler(uid, { documentId, locale, status }) {
 },
 ```
 
-A more detailed example using the draft mode of Next.js is given in the [basic implementation guide](#3-add-handler-logic).
+A more detailed example using the draft mode of Next.js is given in the [basic implementation guide](#3-add-handler).
 
 ## Basic implementation guide
 
-Follow these steps to add Preview capabilities to your content types.
+Follow these steps to add Preview capabilities to your content types in Strapi and your front-end.
+
+This guide uses a basic Next.js example, but the process applies to all frameworks with some variations. Strapi-related steps (prefixed with [Strapi]) remain mostly the same. Please refer to your front-end framework's documentation for specific implementation details.
 
-### 1. Create the Preview configuration
+### 1. [Strapi] Create the Preview configuration {#1-create-config}
 
 Create a new file `/config/admin.ts` (or update it if it exists) with the following basic structure:
 
@@ -127,7 +131,7 @@ export default ({ env }) => ({
 });
 ```
 
-### 2. Add URL generation logic
+### 2. [Strapi] Add URL generation logic {#2-add-url-generation}
 
 Add the URL generation logic with a `getPreviewPathname` function. The following example is taken from the [Launchpad](https://github.com/strapi/LaunchPad/tree/feat/preview) Strapi demo application:
 
@@ -177,7 +181,7 @@ const getPreviewPathname = (uid, { locale, document }): string => {
 Some content types don't need to have a preview if it doesn't make sense, hence the default case returning `null`. A Global single type with some site metadata, for example, will not have a matching front-end page. In these cases, the handler function should return `null`, and the preview UI will not be shown in the admin panel. This is how you enable or disable preview per content type.
 :::
 
-### 3. Add handler logic
+### 3. [Strapi] Add handler logic {#3-add-handler}
 
 Create the complete configuration, expanding the basic configuration created in step 1. with the URL generation logic created in step 2., adding an appropriate handler logic:
 
@@ -225,12 +229,12 @@ export default ({ env }) => {
 };
 ```
 
-### 4. Set up the front-end preview route
+### 4. [Front end] Set up the front-end preview route {#4-setup-frontend-route}
 
 Setting up the front-end preview route is highly dependent on the framework used for your front-end application.
 
 For instance, [Next.js draft mode](https://nextjs.org/docs/app/building-your-application/configuring/draft-mode) and
-[Nuxt preview mode](https://nuxt.com/docs/api/composables/use-preview-mode) provide additional documentation on how to implement the front-end part in their respective documentations.
+[Nuxt preview mode](https://nuxt.com/docs/api/composables/use-preview-mode) provide additional information on how to implement the front-end part in their respective documentations.
 
 If using Next.js, a basic implementation could be like in the following example taken from the [Launchpad](https://github.com/strapi/LaunchPad/tree/feat/preview) Strapi demo application:
 
@@ -264,15 +268,100 @@ export async function GET(request: Request) {
 }
 ```
 
-### 5. Allow the front-end to be embedded
+### 5. [Front end] Allow the front-end to be embedded {#5-allow-frontend-embed}
 
 On the Strapi side, [the `allowedOrigins` configuration parameter](#allowed-origins) allows the admin panel to load the front-end window in an iframe. But allowing the embedding works both ways, so on the front-end side, you also need to allow the window to be embedded in Strapi's admin panel.
 
 This requires the front-end application to have its own header directive, the CSP `frame-ancestors` directive. Setting this directive up depends on how your website is built. For instance, setting this up in Next.js requires a middleware configuration (see [Next.js docs](https://nextjs.org/docs/app/building-your-application/configuring/content-security-policy)).
 
+### 6. [Front end] Detect changes in Strapi and refresh the front-end {#6-refresh-frontend}
+
+Strapi emits a `strapiUpdate` message to inform the front end that data has changed. 
+
+To track this, within your front-end application, add an event listener to listen to events posted through [the `postMessage()` API](https://developer.mozilla.org/en-US/docs/Web/API/Window/postMessage) on the `window` object. The listener needs to filter through messages and react only to Strapi-initiated messages, then refresh the iframe content.
+
+With Next.js, the recommended way to refresh the iframe content is with [the `router.refresh()` method](https://nextjs.org/docs/app/building-your-application/caching#routerrefresh).
+<!-- TODO: use ExternalLink compo. -->
+
+<Tabs groupId="js-ts">
+<TabItem value="js" label="JavaScript" >
+
+```tsx title="next/app/path/to/your/front/end/logic.jsx" {6-17}
+export default function MyClientComponent({...props}) {
+  // …
+  const router = useRouter();
+  
+  useEffect(() => {
+    const handleMessage = async (message) => {
+      if (
+        // Filters events emitted through the postMessage() API
+        message.origin === process.env.NEXT_PUBLIC_API_URL &&
+        message.data.type === "strapiUpdate"
+      ) { // Recommended way to refresh with Next.js
+        router.refresh();
+      }
+    };
+    
+    // Add the event listener
+    window.addEventListener("message", handleMessage);
+    
+    // Cleanup the event listener on unmount
+    return () => {
+      window.removeEventListener("message", handleMessage);
+    };
+  }, [router]);
+  
+  // ...
+}
+```
+
+</TabItem>
+<TabItem value="ts" label="TypeScript" >
+
+```tsx title="next/app/path/to/your/front/end/logic.tsx" {6-17}
+export default function MyClientComponent({
+  //…
+  const router = useRouter();
+
+  useEffect(() => {
+    const handleMessage = async (message: MessageEvent<any>) => {
+      if (
+        // Filters events emitted through the postMessage() API
+        message.origin === process.env.NEXT_PUBLIC_API_URL &&
+        message.data.type === "strapiUpdate"
+      ) { // Recommended way to refresh with Next.js
+        router.refresh();
+      }
+    };
+
+    // Add the event listener
+    window.addEventListener("message", handleMessage);
+
+    // Cleanup the event listener on unmount
+    return () => {
+      window.removeEventListener("message", handleMessage);
+    };
+  }, [router]);
+
+  // …
+})
+```
+
+</TabItem>
+
+</Tabs>
+
+<details>
+<summary>Caching in Next.js:</summary>
+
+In Next.js, [cache persistence](https://nextjs.org/docs/app/building-your-application/caching) may require additional steps. You might need to invalidate the cache by making an API call from the client side to the server, where the revalidation logic will be handled. Please refer to Next.js documentation for details, for instance with the [revalidatePath() method](https://nextjs.org/docs/app/building-your-application/caching#revalidatepath).
+<br/>
+
+</details>
+
 ### Next steps
 
-Once the preview system is set up, you need to adapt your data fetching logic to handle draft content appropriately. This involves:
+Once the preview system is set up, you need to adapt your data fetching logic to handle draft content appropriately. This involves the following steps:
 
 1. Create or adapt your data fetching utility to check if draft mode is enabled
 2. Update your API calls to include the draft status parameter when appropriate

docusaurus/docs/user-docs/content-manager/previewing-content.md

@@ -11,38 +11,36 @@ tags:
 
 With the Preview feature, you can preview your front end application directly from Strapi's admin panel. This is helpful to see how updates to your content in the Edit View of the Content Manager will affect the final result.
 
-<!-- TODO: add a dark mode GIF -->
-<ThemedImage
-  alt="Previewing content"
-  sources={{
-    light: '/img/assets/content-manager/previewing-content.gif',
-    dark: '/img/assets/content-manager/previewing-content.gif',
-  }}
-/>
-
 :::prerequisites
 - The Strapi admin panel user should have read permissions for the content-type.
 - The Preview feature should be configured in the code of the `config/admin` file (see [Developer Docs](/dev-docs/preview)).
 - A front-end application should already be created and running so you can preview it.
+- Additionally, the side panel is only available if you installed strapi with the beta flag, with the following command: `npx create-strapi@beta`.
 :::
 
-When the Preview feature is properly set up, an **Open preview** button is visible on the right in the Edit View of the Content Manager. Clicking it will display the preview of your content as it will appear in your front-end application, but directly within Strapi's the admin panel:
+Once the Preview feature is properly set up, an **Open preview** button is visible on the right in the Edit View of the Content Manager. Clicking it will display a side panel with the preview of your content as it will appear in your front-end application, but directly within Strapi's the admin panel.
 
 <!-- TODO: add a dark mode screenshot -->
 <ThemedImage
   alt="Previewing content"
   sources={{
-    light: '/img/assets/content-manager/previewing-content.png',
-    dark: '/img/assets/content-manager/previewing-content.png',
+    light: '/img/assets/content-manager/previewing-content2.gif',
+    dark: '/img/assets/content-manager/previewing-content2.gif',
   }}
 />
 
-From the Preview screen, you can:
+Once the side panel for the Preview is open, you can:
 
 - click the close button ![Close button](/img/assets/icons/close-icon.svg) in the upper left corner to go back to the Edit View of the Content Manager,
 - switch between previewing the draft and the published version (if [Draft & Publish](/user-docs/content-manager/saving-and-publishing-content) is enabled for the content-type),
+- expand the side panel by clicking on the <Icon name="arrow-line-left" classes="ph-bold" /> button to make the Preview  full screen
+- use buttons at the top right of the editor to define the assignee and stage for the [Review Workflows feature](/user-docs/content-manager/reviewing-content) if enabled
 - and click the link icon ![Link icon](/img/assets/icons/v5/Link.svg) in the upper right corner to copy the preview link. Depending on the preview tab you are currently viewing, this will either copy the link to the preview of the draft or the published version.
 
+:::info
+The side panel and its expand button are only available if you run the beta version of Strapi. In the stable version, the "Open Preview" button will open a full-screen preview.
+:::
+
 :::note
 In the Edit view of the Content Manager, the Open preview button will be disabled if you have unsaved changes. Save your latest changes and you should be able to preview content again.
 :::

docusaurus/sidebars.js

@@ -295,7 +295,7 @@ const sidebars = {
           label: 'Preview',
           id: 'dev-docs/preview',
           customProps: {
-            new: true
+            updated: true
           }
         },
         {
@@ -669,7 +669,7 @@ const sidebars = {
           type: 'doc',
           id: 'user-docs/content-manager/previewing-content',
           customProps: {
-            new: true
+            updated: true
           }
         },
         'user-docs/content-manager/adding-content-to-releases',