Merge branch 'main' of github.com:strapi/documentation

Author: meganelacheny

docusaurus/docs/cloud/projects/settings.md

@@ -414,8 +414,23 @@ Environment variables (more information in the [Developer Documentation](../../d
   }}
 />
 
-In the <Icon name="code" classes="ph-bold" /> *Variables* tab, you can:
-- click the **Add variable** button to create a new variable
-- edit any variable, each being composed of a *Name* and a *Value*
-- click the <Icon name="trash-simple" /> delete button associated with any non-default variable to delete it
-- click the **Save** button to save any change made on the page
+In the <Icon name="code" classes="ph-bold" /> *Variables* tab are listed both the default and custom environment variables for your Strapi Cloud project. Each variable is composed of a *Name* and a *Value*.
+
+#### Managing environment variables
+
+Hovering on an environment variable, either default or custom, displays the following available options:
+
+- <Icon name="eye" /> **Show value** to replace the `*` characters with the actual value of a variable.
+- <Icon name="copy" /> **Copy to clipboard** to copy the value of a variable.
+- <Icon name="dots-three" /> **Actions** to access the <Icon name="pencil-simple" /> Edit and <Icon name="trash-simple" /> Delete buttons. Both options are only available for custom environment variables.
+  - When editing a variable, don't forget to confirm the changes by clicking on **Save**.
+  - When deleting a variable, you will be asked to click on a **Confirm** button to confirm the deletion.
+
+#### Creating custom environment variables
+
+Custom environment variables can be created for the Strapi Cloud project. Make sure to redeploy your project after creating or editing an environment variable.
+
+1. In the *Custom environment variables* section, click on the **Add variable** button.
+2. Write the *Name* and *Value* of the new environment variable in the same-named fields.
+3. (optional) Click on **Add another** to directly create one or more other custom environment variables.
+4. Click on the **Save** button to confirm the creation of the custom environment variables.

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/managing-relational-fields.md

@@ -95,7 +95,7 @@ To select the relevant relational field's entries:
 3. Repeat step 2 until all relevant entries have been chosen.
 
 :::tip
-All selected entries are listed right below the drop-down list. Click on the name of an entry to be redirected to the edit view of the relational field's content-type. Make sure you save your page first, to avoid losing your last modifications.
+All selected entries are listed right below the drop-down list. Click on the name of an entry to display a modal from where you will be able to edit the relational field's content-type. For now, you can only edit a relation on-the-fly, and not create a new one. This feature is currently in beta and only available if you installed Strapi with the beta flag, with the following command `npx create-strapi@beta`.
 :::
 
 To remove an entry, click on the cross button <Icon name="x" classes="ph-bold" /> in the selected entries list.

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "strapi-docs",
-  "version": "5.6.3",
+  "version": "5.6.4",
   "private": true,
   "scripts": {
     "docusaurus": "docusaurus",

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',