@dotcms/vue 1.5.5 → 1.7.0

package/README.md

@@ -14,12 +14,14 @@ The `@dotcms/vue` SDK is the dotCMS official Vue 3 library. It empowers Vue deve
 -   [Quickstart: Render a Page with dotCMS](#quickstart-render-a-page-with-dotcms)
     -   [Example Project](#example-project-)
 -   [SDK Reference](#sdk-reference)
+    -   [createDotCMSVue / useDotCMSClient](#createdotcmsvue--usedotcmsclient)
     -   [DotCMSLayoutBody](#dotcmslayoutbody)
     -   [DotCMSEditableText](#dotcmseditabletext)
     -   [DotCMSBlockEditorRenderer](#dotcmsblockeditorrenderer)
     -   [DotCMSShow](#dotcmsshow)
     -   [useEditableDotCMSPage](#useeditabledotcmspage)
     -   [useDotCMSShowWhen](#usedotcmsshowwhen)
+    -   [createDotCMSImageLoader](#createdotcmsimageloader)
     -   [toPlain](#toplain)
 -   [Troubleshooting](#troubleshooting)
     -   [Common Issues & Solutions](#common-issues--solutions)
@@ -95,17 +97,67 @@ Requires **Vue 3.4+** (declared as a peer dependency). The install also brings i
 
 ### dotCMS Client Configuration
 
+Install the dotCMS Vue plugin once at startup. It builds the client and provides
+it to the whole app, so components retrieve it with `useDotCMSClient()` instead
+of importing a module-level singleton — the Vue analog of Angular's
+`provideDotCMSClient`.
+
+```ts
+// main.ts
+import { createApp } from 'vue';
+import { createDotCMSVue } from '@dotcms/vue';
+
+import App from './App.vue';
+
+const app = createApp(App);
+
+app.use(
+    createDotCMSVue({
+        dotcmsUrl: import.meta.env.VITE_DOTCMS_HOST,
+        authToken: import.meta.env.VITE_DOTCMS_AUTH_TOKEN, // Optional for public content
+        siteId: import.meta.env.VITE_DOTCMS_SITE_ID, // Optional site identifier/name
+        requestOptions: {
+            // The UVE needs fresh data so in-context edits are reflected immediately.
+            cache: 'no-cache'
+        }
+    })
+);
+
+app.mount('#app');
+```
+
+Then, in any component:
+
+```vue
+<script setup lang="ts">
+import { useDotCMSClient } from '@dotcms/vue';
+
+const client = useDotCMSClient();
+const { pageAsset } = await client.page.get('/');
+</script>
+```
+
+> **Using the client outside a component?** Code that runs before/outside a
+> component `setup` — e.g. a Vue Router page loader — can't call
+> `useDotCMSClient()`. Keep a reference to the plugin and read its `.client`:
+>
+> ```ts
+> export const dotCMSVue = createDotCMSVue({ ...config });
+> export const dotCMSClient = dotCMSVue.client; // same instance the plugin provides
+> ```
+
+If you prefer to manage the client yourself, `createDotCMSClient` from
+`@dotcms/client` is still available and works with all of this SDK's components
+and composables — the plugin is a convenience, not a requirement.
+
 ```typescript
 import { createDotCMSClient } from '@dotcms/client';
 
 export const dotCMSClient = createDotCMSClient({
     dotcmsUrl: import.meta.env.VITE_DOTCMS_HOST,
-    authToken: import.meta.env.VITE_DOTCMS_AUTH_TOKEN, // Optional for public content
-    siteId: import.meta.env.VITE_DOTCMS_SITE_ID, // Optional site identifier/name
-    requestOptions: {
-        // The UVE needs fresh data so in-context edits are reflected immediately.
-        cache: 'no-cache'
-    }
+    authToken: import.meta.env.VITE_DOTCMS_AUTH_TOKEN,
+    siteId: import.meta.env.VITE_DOTCMS_SITE_ID,
+    requestOptions: { cache: 'no-cache' }
 });
 ```
 
@@ -224,6 +276,26 @@ Looking to get started quickly? Our [Vue.js starter project](https://github.com/
 
 All components, composables and utilities are imported from `@dotcms/vue`.
 
+### createDotCMSVue / useDotCMSClient
+
+`createDotCMSVue(config)` returns a Vue plugin that builds a dotCMS client and
+provides it app-wide. `useDotCMSClient()` retrieves that client from any
+component. See [dotCMS Client Configuration](#dotcms-client-configuration) for
+the full setup.
+
+```ts
+import { createDotCMSVue } from '@dotcms/vue';
+
+const plugin = createDotCMSVue({ dotcmsUrl, authToken /* …DotCMSClientConfig */ });
+app.use(plugin);
+```
+
+| Export                    | Signature                                            | Description                                                                                     |
+| ------------------------- | ---------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
+| `createDotCMSVue(config)` | `(config: DotCMSClientConfig) => DotCMSVuePlugin`    | Vue plugin for `app.use()`. `config` is the same object accepted by `createDotCMSClient`.       |
+| `useDotCMSClient()`       | `() => DotCMSClient`                                 | Returns the provided client. Throws if the plugin was not installed. Call it inside `setup`.    |
+| `DotCMSVuePlugin.client`  | `DotCMSClient`                                        | The created client instance, for use outside components (e.g. router loaders).                  |
+
 ### DotCMSLayoutBody
 
 `DotCMSLayoutBody` renders the layout for a dotCMS page (rows → columns → containers → contentlets), dispatching each contentlet to the mapped component. It supports both production and development modes.
@@ -281,6 +353,28 @@ const components = {
 > [!TIP]
 > Always use the exact content type variable name from dotCMS as the key. You can find it in the Content Types section of your dotCMS admin panel.
 
+#### Per-contentlet slots
+
+Beyond mapping by content type, you can override a **specific** contentlet by
+its `identifier` using a named slot: `#contentlet-<identifier>`. When present,
+the slot renders instead of the mapped component — the Vue analog of the React
+SDK's `slots` prop, useful for one-off custom markup or a pre-rendered node.
+
+The contentlet is exposed as the slot's scope prop.
+
+```vue
+<template>
+    <DotCMSLayoutBody :page="page" :components="components">
+        <!-- Renders instead of the Blog component for this one contentlet -->
+        <template #contentlet-a1b2c3d4="{ contentlet }">
+            <FeaturedBlog :blog="contentlet" />
+        </template>
+    </DotCMSLayoutBody>
+</template>
+```
+
+Contentlets without a matching slot fall back to the `components` mapping as usual.
+
 ### DotCMSEditableText
 
 `DotCMSEditableText` enables inline editing of a single text field in dotCMS. Inside the UVE in edit mode it mounts a TinyMCE editor; everywhere else it renders the field's current value.
@@ -330,6 +424,20 @@ const props = defineProps<{ contentlet: DotCMSBasicContentlet }>();
 | `style`           | `CSSProperties`             | ❌       | -       | Inline styles for the container                                 |
 | `isDevMode`       | `boolean`                   | ❌       | `false` | When `true`, shows a visible message for invalid/unknown blocks |
 
+> **`className`/`style` vs native `class`/`style`:** the `className` and `style`
+> props mirror the React SDK so the same code shape works across frameworks. This
+> component renders one of two root elements (an error box or the content
+> container), so Vue's automatic attribute fallthrough does **not** apply — a
+> native `class="prose"` on the tag will not reach the container. Use the
+> `className` and `style` props to style the container:
+>
+> ```vue
+> <DotCMSBlockEditorRenderer
+>     :blocks="contentlet.body"
+>     class-name="prose max-w-none"
+>     :style="{ marginTop: '1rem' }" />
+> ```
+
 #### Usage
 
 A custom renderer is a Vue component that receives the block as a `node` prop and the rendered children in its default `<slot />`.
@@ -465,6 +573,46 @@ const isEditMode = useDotCMSShowWhen(UVE_MODE.EDIT); // Readonly<Ref<boolean>>
 </template>
 ```
 
+### createDotCMSImageLoader
+
+`createDotCMSImageLoader(dotcmsUrl?)` returns a function that turns a dotCMS asset identifier (or path) into an optimized image URL via the dotCMS image API (the `/dA/` route, which handles resizing and optimization). It's the Vue analog of Angular's `provideDotCMSImageLoader` — Vue has no `IMAGE_LOADER` token, so you call the returned function directly.
+
+Absolute `http(s)://…` URLs are returned unchanged, so mixing dotCMS assets with external/stock imagery just works.
+
+| Argument    | Type     | Required | Default | Description                                                                              |
+| ----------- | -------- | -------- | ------- | ---------------------------------------------------------------------------------------- |
+| `dotcmsUrl` | `string` | ❌       | `''`    | Base URL of your dotCMS instance. Omit (empty) for site-relative `/dA/…` behind a proxy. |
+
+The returned loader is `(src: string, options?) => string`, where `options` is `{ width?, quality?, languageId? }` (`quality` defaults to `50`, `languageId` to `'1'`).
+
+```ts
+import { createDotCMSImageLoader } from '@dotcms/vue';
+
+// Absolute (production)
+const image = createDotCMSImageLoader(import.meta.env.VITE_DOTCMS_HOST);
+image(contentlet.inode, { width: 800 });
+// → https://demo.dotcms.com/dA/<inode>/800w/50q?language_id=1
+
+// Site-relative (dev proxy) — omit the host so the Vite /dA proxy handles it
+const proxied = createDotCMSImageLoader();
+proxied(contentlet.inode, { width: 800 }); // → /dA/<inode>/800w/50q?language_id=1
+```
+
+```vue
+<script setup lang="ts">
+import { createDotCMSImageLoader } from '@dotcms/vue';
+import type { DotCMSBasicContentlet } from '@dotcms/types';
+
+const props = defineProps<{ contentlet: DotCMSBasicContentlet }>();
+
+const image = createDotCMSImageLoader(import.meta.env.VITE_DOTCMS_HOST);
+</script>
+
+<template>
+    <img :src="image(contentlet.inode, { width: 800 })" :alt="contentlet.title" />
+</template>
+```
+
 ### toPlain
 
 `toPlain` deep-unwraps a Vue reactive value (refs / reactive proxies) into a plain, structured-clone-safe object. Use it before passing reactive data to UVE editor actions (`editContentlet`, `enableBlockEditorInline`, …) from `@dotcms/uve`, which send their argument to the editor via `postMessage`.

package/index.d.ts

@@ -1,6 +1,10 @@
+export { createDotCMSVue, useDotCMSClient, DOTCMS_CLIENT } from './lib/client/dotcms-client.plugin';
+export type { DotCMSClient, DotCMSVuePlugin } from './lib/client/dotcms-client.plugin';
 export { useEditableDotCMSPage } from './lib/composables/useEditableDotCMSPage';
 export { useDotCMSShowWhen } from './lib/composables/useDotCMSShowWhen';
 export { toPlain } from './lib/utils/toPlain';
+export { createDotCMSImageLoader } from './lib/utils/imageLoader';
+export type { DotCMSImageLoader, DotCMSImageLoaderOptions } from './lib/utils/imageLoader';
 export { default as DotCMSShow } from './lib/components/DotCMSShow/DotCMSShow.vue';
 export { default as DotCMSLayoutBody } from './lib/components/DotCMSLayoutBody/DotCMSLayoutBody.vue';
 export { default as DotCMSEditableText } from './lib/components/DotCMSEditableText/DotCMSEditableText.vue';