chore(SDK): update SDK README.md Documentation #32192
Conversation
|
Please use a Conventional Commit title format for this PR. For more information, see https://www.conventionalcommits.org/en/v1.0.0/ |
rjvelazco
changed the title
…n Angular and React SDK documentation
…ces, improved structure, and troubleshooting tips
core-web/libs/sdk/client/README.md
Outdated
| const blogs = await client.content | ||
| .getCollection('Blog') | ||
| .query((qb) => | ||
| qb.field('title').contains('dotCMS').and().field('publishDate').greaterThan('2023-01-01') | ||
| ) | ||
| .limit(10) | ||
| .page(1) | ||
| .fetch(); |
There was a problem hiding this comment.
Check the tests this code is not right
core-web/libs/sdk/angular/README.md
Outdated
| Once configured, image URLs in your components will automatically be proxied to your dotCMS instance: | ||
|
|
||
| ```typescript | ||
| export class YourComponent { | ||
| private readonly client = inject(DOTCMS_CLIENT_TOKEN); | ||
|
|
||
| this.client.page | ||
| .get({ ...pageParams }) | ||
| .then((response) => { | ||
| // Use your response | ||
| }) | ||
| .catch((e) => { | ||
| const error: PageError = { | ||
| message: e.message, | ||
| status: e.status, | ||
| }; | ||
| // Use the error response | ||
| }) | ||
| @Component({ | ||
| template: ` | ||
| <img [src]="'/dA/' + contentlet.inode" alt="Asset from dotCMS" /> | ||
| ` | ||
| }) | ||
| class MyDotCMSImageComponent { | ||
| @Input() contentlet: DotCMSBasicContentlet; | ||
| } | ||
| ``` |
There was a problem hiding this comment.
Didn't @nicobytes wrote something to use the new image directive on this?
There was a problem hiding this comment.
I'll check/review this after addressing the rest of the feedback!
core-web/libs/sdk/uve/README.md
Outdated
|
|
||
| The library exposes three main entry points: | ||
| That's it! You can now start using the UVE SDK in your application. |
There was a problem hiding this comment.
Is not it yet... only starting 😂
core-web/libs/sdk/uve/README.md
Outdated
| ```typescript | ||
| import { getUVEState, createUVESubscription, editContentlet } from '@dotcms/uve'; | ||
| import { UVEEventType, UVE_MODE } from '@dotcms/uve/types'; | ||
| import { initUVE, editContentlet } from '@dotcms/uve'; | ||
|
|
||
| // Check if we're in the editor | ||
| const uveState = getUVEState(); | ||
| if (uveState?.mode === UVE_MODE.EDIT) { | ||
| console.log('Running in edit mode!'); | ||
|
|
||
| // Subscribe to content changes | ||
| const subscription = createUVESubscription(UVEEventType.CONTENT_CHANGES, (changes) => { | ||
| console.log('Content updated:', changes); | ||
| // Update your UI with the new content | ||
| }); | ||
|
|
||
| // Later, when no longer needed | ||
| subscription.unsubscribe(); | ||
| } | ||
| // Initialize the UVE | ||
| const UVE_PARAMS = { | ||
| languageId: '1', | ||
| depth: 3 | ||
| }; | ||
|
|
||
| initUVE({ params: UVE_PARAMS }); | ||
|
|
||
| // Get the edit button | ||
| const myEditButton = document.getElementById('my-edit-button'); | ||
|
|
||
| // Add an event listener to the edit button | ||
| myEditButton.addEventListener('click', () => { | ||
| const contentlet = document.getElementById('my-contentlet').dataset.contentlet; | ||
| // Open the modal editor for the contentlet | ||
| editContentlet(contentlet); | ||
| }); |
There was a problem hiding this comment.
This doesn't make sense it will confuse readers more. We need to provide this in the context of using @dotcms/client and be very opinionated and say "this won't work without it" because I don't want to have to support crazy implementations. Let's be opinionated here.
core-web/libs/sdk/uve/README.md
Outdated
| ### `initUVE(config?: DotCMSUVEConfig)` | ||
|
|
||
| #### `getUVEState` | ||
| **Overview**: Initializing UVE is the crucial first step to connect your application with the dotCMS Universal Visual Editor (UVE). It sets up the necessary communication between your app and the editor, enabling seamless integration and interaction. | ||
|
|
||
| Retrieves the current UVE state. | ||
| **Parameters**: | ||
|
|
||
| **Returns:** | ||
| - A `UVEState` object if running inside the editor, or `undefined` otherwise. | ||
| | Name | Type | Required | Description | | ||
| | -------- | ----------------- | -------- | ----------------------------------------- | | ||
| | `config` | `DotCMSUVEConfig` | ❌ | Optional setup for language, persona, etc | | ||
|
|
||
| The state includes: | ||
| - `mode`: The current editor mode (preview, edit, live). | ||
| - `languageId`: The language ID of the current page set in the UVE. | ||
| - `persona`: The persona of the current page set in the UVE. | ||
| - `variantName`: The name of the current variant. | ||
| - `experimentId`: The ID of the current experiment. | ||
| - `publishDate`: The publish date of the current page set in the UVE. | ||
| **Usage:** | ||
|
|
||
| > **Note:** If any of these properties are absent, it means the value is the default one. | ||
| ```ts | ||
| const { destroyUVESubscriptions } = initUVE({ params }); | ||
| ``` | ||
|
|
||
| **Example:** | ||
| ```typescript | ||
| const editorState = getUVEState(); | ||
| if (editorState?.mode === 'edit') { | ||
| // Enable editing features | ||
| #### UVE Configuration | ||
|
|
||
| - `graphql` (object - optional): The graphql query to execute | ||
| - `query` (string): The graphql query to execute | ||
| - `variables` (object): The variables to pass to the graphql query. | ||
| - `params` (object - optional): The parameters to pass to the page API | ||
| - `languageId` (string): The language ID of the current page set on the UVE. | ||
| - `personaId` (string): The persona ID of the current page set on the UVE. | ||
| - `publishDate` (string): The publish date of the current page set on the UVE. | ||
| - `depth` (0-3): The depth of the current page set on the UVE. | ||
| - `fireRules` (boolean): Indicates whether you want to fire the rules set on the page. | ||
| - `variantName` (string): The name of the current variant. |
There was a problem hiding this comment.
Maybe we can say "this config comes from client.page.get" if not we can assure it will work as expected.
… improve clarity across Angular, React, and UVE sections
| | `contentlet` | `DotCMSContentlet` | ✅ | The contentlet containing the editable field | | ||
| | `fieldName` | `string` | ✅ | Name of the field to edit | |
There was a problem hiding this comment.
Now contentlet is type T extends DotCMSContentlet and fieldName is a keyof of that T
I think the current DotCMSContentlet and string description is more clear and easy to undersand to the user, so i suggest to keep it or replace fieldName with "keyof the contentlet" or something
But what do you think? @rjvelazco @zJaaal @fmontes
There was a problem hiding this comment.
Oh, let me update this
| - **Simplified Development**: Write less code with intuitive methods and builders | ||
| - **Type Safety**: Built-in TypeScript definitions prevent runtime errors | ||
| - **Universal Compatibility**: Works in both browser and Node.js environments | ||
| - **Performance Optimized**: Built-in caching and efficient data fetching |
There was a problem hiding this comment.
Probably but it reads like the lib have the cache.
| Create a `proxy.conf.json` file in your project: | ||
|
|
||
| ```json | ||
| // proxy.conf.json |
There was a problem hiding this comment.
If we use use proxy.conf.js we can use the env variable for the host. For next version thing.
| // /components/my-dotcms-image.component.ts | ||
| @Component({ | ||
| template: ` | ||
| <img [src]="'/dA/' + contentlet.inode" alt="Asset from dotCMS" /> |
There was a problem hiding this comment.
Probably we want to add this to our SDK: https://docs.google.com/document/d/1n1O9SMNh2z3_LriSiX8Dd9F4pryfVNqMwjY9azL0vNU/edit?tab=t.0#heading=h.suaidt1do8jz
Update the dotCMS SDKs documentation
README.md