-
Notifications
You must be signed in to change notification settings - Fork 16
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
feat: update documentation + expose csm rest api function (#687)
* docs: add csm readme * feat: expose cpa response in lp sdk * docs: examples explanation * chore: update examples to latest sdk version * feat: address pr concerns
- Loading branch information
1 parent
7b4ebbd
commit 39a2198
Showing
10 changed files
with
138 additions
and
46 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,33 @@ | ||
| # Example Projects Overview | ||
|
|
||
| This README provides a comprehensive overview of our various example projects to assist you in selecting the most appropriate example based on your specific requirements. | ||
|
|
||
| ## next-app-router (recommended) | ||
|
|
||
| Client-Side Hydration: This setup integrates client components, facilitating the client-side hydration of HTML, CSS, and JavaScript. This feature enables the use of hooks for instant live updates directly in the browser. | ||
| Real-Time Live Updates: Features a live update system that allows fields to dynamically update as edits are made, providing immediate feedback without requiring a save action. | ||
|
|
||
| ## next-14-app-router-ssr | ||
|
|
||
| Server-Side Rendering (SSR) Focus: This example exclusively utilizes server-side rendering, with minimal client-side interactions limited to loading the Live Preview SDK in a standalone script. | ||
| Conditional Revalidation: Configured to trigger a revalidation process through a designated endpoint whenever changes are saved in Contentful, refreshing the page to display new content after a brief delay of 5 seconds. | ||
|
|
||
| ## next-13-app-router-ssr | ||
|
|
||
| Enhanced SSR with Client-Side Reloading: Operates similarly to the next-14-app-router-ssr but includes a script that forcefully reloads the iframe if an entry’s save event is detected in Contentful, effective after 5-seconds. This script supports both Next 13 and Next 14 versions. | ||
|
|
||
| ## next-pages-router | ||
|
|
||
| Integration with Pages Router: Demonstrates how to utilize the `@contentful/live-preview` SDK within a Next.js Pages Router setup. | ||
|
|
||
| ## Remix | ||
|
|
||
| Remix Framework Compatibility: Provides an example of how to integrate the `@contentful/live-preview` SDK with a Remix application. | ||
|
|
||
| ## Vanilla JS | ||
|
|
||
| Offers a basic demonstration of employing the `@contentful/live-preview` SDK within a straightforward Vanilla JavaScript environment. | ||
|
|
||
| ## Gatsby | ||
|
|
||
| Limited Gatsby Support: Currently, while Inspector Mode is operational in Gatsby, there is an issue with live updates. Due to Gatsby's unique processing of data from the Content Preview API into its GraphQL schema, live updates via the Live Preview SDK are not supported. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,3 +1,97 @@ | ||
| > ⚠️ **This feature is currently in alpha for selected customers.** | ||
| # Content Source Maps | ||
|
|
||
| > The base for generating Content Source Maps with Contentful | ||
| Automatically add inspector mode to visual fields such as short text, rich text and assets, eliminating the time and effort required for manually inserting data attributes. | ||
|
|
||
| ## Installation | ||
|
|
||
| Install the Live Preview SDK: | ||
|
|
||
| ```bash | ||
| npm install @contentful/live-preview | ||
| ``` | ||
|
|
||
| ## How it works | ||
|
|
||
| The Live Preview SDK transforms the Content Source Maps coming from either the GraphQL API or Content Preview API (REST) into hidden metadata. This process employs steganography to conceal metadata within invisible Unicode characters, containing information to activate inspector mode. These invisible Unicode characters will not alter the visual presentation of your content. | ||
|
|
||
| ### GraphQL | ||
|
|
||
| #### 1. Setting Up GraphQL Queries | ||
|
|
||
| Enable Content Source Maps in your GraphQL queries as follows: | ||
|
|
||
| ```graphql | ||
| query @contentSourceMaps { | ||
| postCollection(preview: true) { | ||
| items { | ||
| title | ||
| } | ||
| } | ||
| } | ||
| ``` | ||
|
|
||
| The GraphQL API will now return the data along with the Content Source Maps in the `extensions` field. | ||
|
|
||
| #### 2. Processing GraphQL Response | ||
|
|
||
| Then, pass the data to the provided function `encodeGraphQLResponse` to encode the response: | ||
|
|
||
| ```jsx | ||
| import { encodeGraphQLResponse } from '@contentful/live-preview'; | ||
|
|
||
| const dataWithAutoTagging = encodeGraphQLResponse(data); | ||
| ``` | ||
|
|
||
| When rendering the encoded data in your website, inspector mode will activate automatically. | ||
|
|
||
| ### REST (Content Preview API) | ||
|
|
||
| #### 1. Enable Content Source Maps for the CPA | ||
|
|
||
| To enable Content Source Maps using the [Contentful Client SDK](https://github.com/contentful/contentful.js), simply integrate the `alpha_withContentSourceMaps` chain modifier as shown below: | ||
|
|
||
| ```jsx | ||
| import { getEntries } from 'contentful'; | ||
|
|
||
| const entries = await client.alpha_withContentSourceMaps.getEntries(); | ||
| ``` | ||
|
|
||
| The CPA will include Content Source Maps within the `sys` object of the response. | ||
|
|
||
| #### 2. Processing CPA Response | ||
|
|
||
| Then, pass the data to the provided function `encodeCPAResponse` to encode the response: | ||
|
|
||
| ```jsx | ||
| import { encodeCPAResponse } from '@contentful/live-preview'; | ||
|
|
||
| const dataWithAutoTagging = encodeCPAResponse(data); | ||
| ``` | ||
|
|
||
| When rendering the encoded data in your website, inspector mode will activate automatically. | ||
|
|
||
| ## Troubleshooting / Tips | ||
|
|
||
| - Under certain circumstances, such as when applying letter-spacing in CSS, fields may display styles that weren't intended. In these cases, you can utilize the `splitEncoding` function provided by the Live Preview SDK to retrieve the content and remove any hidden metadata. | ||
|
|
||
| ```jsx | ||
| import { splitEncoding } from '@contentful/live-preview'; | ||
|
|
||
| const { cleaned, encoded } = splitEncoding(text); | ||
| ``` | ||
|
|
||
| - Images will get automatically tagged if you provide an alt attribute with the asset title or description. | ||
|
|
||
| - To stop using manual tags while using Content Source Maps: | ||
|
|
||
| ```jsx | ||
| <ContentfulLivePreviewProvider experimental={{ ignoreManuallyTaggedElements: true }} /> | ||
| ``` | ||
|
|
||
| ## Limitations | ||
|
|
||
| - Markdown support is currently in development. | ||
| - Adding hidden metadata to content can result in problems, e.g. when being used for CSS values, for dates or URL content. You can remove the hidden strings using the `splitEncoding` function from the Live Preview SDK. | ||
| - Hidden strings will not be generated for fields that end with numeric values. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters