Skip to content

Commit

Permalink
Merge pull request #767 from storyblok/chore/correct-docs-richtext
Browse files Browse the repository at this point in the history 
chore: correct docs richtext
  • Loading branch information
@alvarosabu
alvarosabu authored Nov 30, 2024
2 parents ca45ff5 + 2eebf45 commit 5282259
Showing 1 changed file with 171 additions and 155 deletions.
326 changes: 171 additions & 155 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -128,161 +128,6 @@ The simplest way is by using the `useStoryblok` one-liner composable. Where you

Check the available [apiOptions](https://www.storyblok.com/docs/api/content-delivery/v2#core-resources/stories/retrieve-one-story?utm_source=github.com&utm_medium=readme&utm_campaign=storyblok-vue) in our API docs and [bridgeOptions](https://www.storyblok.com/docs/Guides/storyblok-latest-js?utm_source=github.com&utm_medium=readme&utm_campaign=storyblok-vue) passed to the Storyblok Bridge.

### Rendering Rich Text

You can render rich-text fields by using the `StoryblokRichText` component:

```html
<script setup>
import { StoryblokRichText } from "@storyblok/vue";
</script>

<template>
<StoryblokRichText :doc="blok.articleContent" />
</template>
```

#### Overriding the default resolvers

You can override the default resolvers by passing a `resolver` prop to the `StoryblokRichText` component, for example, to use vue-router links or add a custom codeblok component: :

```html
<script setup>
import { type VNode, h } from "vue";
import { StoryblokRichText, BlockTypes, MarkTypes, type StoryblokRichTextNode } from "@storyblok/vue";
import { RouterLink } from "vue-router";
import CodeBlok from "./components/CodeBlok.vue";
const resolvers = {
// RouterLink example:
[MarkTypes.LINK]: (node: StoryblokRichTextNode<VNode>) => {
return node.attrs?.linktype === 'STORY'
? h(RouterLink, {
to: node.attrs?.href,
target: node.attrs?.target,
}, node.text)
: h('a', {
href: node.attrs?.href,
target: node.attrs?.target,
}, node.text)
},
// Custom code block component example:
[BlockTypes.CODE_BLOCK]: (node: Node) => {
return h(CodeBlock, {
class: node?.attrs?.class,
}, node.children)
},
}
</script>
<template>
<StoryblokRichText :doc="blok.articleContent" :resolvers="resolvers" />
</template>
```
Or you can have more control by using the `useStoryblokRichText` composable:
```html
<script setup>
import { type VNode, h } from "vue";
import { useStoryblokRichText, BlockTypes, MarkTypes, type StoryblokRichTextNode } from "@storyblok/vue";
import { RouterLink } from "vue-router";
const resolvers = {
// RouterLink example:
[MarkTypes.LINK]: (node: StoryblokRichTextNode<VNode>) => {
return node.attrs?.linktype === 'STORY'
? h(RouterLink, {
to: node.attrs?.href,
target: node.attrs?.target,
}, node.text)
: h('a', {
href: node.attrs?.href,
target: node.attrs?.target,
}, node.text)
},
}
const { render } = useStoryblokRichText({
resolvers,
})
const html = render(blok.articleContent);
</script>
<template>
<div v-html="html"></div>
</template>
```
For more incredible options you can pass to the `useStoryblokRichtext, please consult the [Full options](https://github.com/storyblok/richtext?tab=readme-ov-file#options) documentation.
### Legacy Rich Text Resolver
> [!WARNING]
> The legacy `richTextResolver` is soon to be deprecated. We recommend migrating to the new `useRichText` composable described above instead.
You can easily render rich text by using the `renderRichText` function that comes with `@storyblok/vue` and a Vue computed property:
```html
<template>
<div v-html="articleContent"></div>
</template>
<script setup>
import { computed } from "vue";
import { renderRichText } from "@storyblok/vue";
const articleContent = computed(() => renderRichText(blok.articleContent));
</script>
```
You can set a **custom Schema and component resolver globally** at init time by using the `richText` init option:
```js
import { RichTextSchema, StoryblokVue } from "@storyblok/vue";
import cloneDeep from "clone-deep";
const mySchema = cloneDeep(RichTextSchema); // you can make a copy of the default RichTextSchema
// ... and edit the nodes and marks, or add your own.
// Check the base RichTextSchema source here https://github.com/storyblok/storyblok-js-client/blob/master/source/schema.js
app.use(StoryblokVue, {
accessToken: "YOUR_ACCESS_TOKEN",
use: [apiPlugin],
richText: {
schema: mySchema,
resolver: (component, blok) => {
switch (component) {
case "my-custom-component":
return `<div class="my-component-class">${blok.text}</div>`;
default:
return "Resolver not defined";
}
},
},
});
```
You can also set a **custom Schema and component resolver only once** by passing the options as the second parameter to `renderRichText` function:
```js
import { renderRichText } from "@storyblok/vue";
renderRichText(blok.richTextField, {
schema: mySchema,
resolver: (component, blok) => {
switch (component) {
case "my-custom-component":
return `<div class="my-component-class">${blok.text}</div>`;
break;
default:
return `Component ${component} not found`;
}
},
});
```
### Long Form

#### 1. Fetching Content
Expand Down Expand Up @@ -495,6 +340,177 @@ app.use(StoryblokVue, {
app.component("MyCustomFallback", MyCustomFallback);
```

## Rendering Rich Text

You can render rich text fields by using the `StoryblokRichText` component:

```html
<script setup>
import { StoryblokRichText } from "@storyblok/vue";
</script>

<template>
<StoryblokRichText :doc="blok.articleContent" />
</template>
```

Or you can have more control by using the `useStoryblokRichText` composable:

```html
<script setup>
import { useStoryblokRichText } from "@storyblok/vue";
const { render } = useStoryblokRichText({
// options like resolvers
});
const root = () => render(blok.articleContent);
</script>

<template>
<root />
</template>
```

For more incredible options you can pass to the `useStoryblokRichText`, please consult the [Full options](https://github.com/storyblok/richtext?tab=readme-ov-file#options) documentation.

### Overriding the default resolvers

You can override the default resolvers by passing a `resolver` prop to the `StoryblokRichText` component, for example, to use vue-router links or add a custom codeblok component: :

```html
<script setup>
import { type VNode, h } from "vue";
import { StoryblokRichText, BlockTypes, MarkTypes, type StoryblokRichTextNode } from "@storyblok/vue";
import { RouterLink } from "vue-router";
import CodeBlok from "./components/CodeBlok.vue";
const resolvers = {
// RouterLink example:
[MarkTypes.LINK]: (node: StoryblokRichTextNode<VNode>) => {
return node.attrs?.linktype === 'STORY'
? h(RouterLink, {
to: node.attrs?.href,
target: node.attrs?.target,
}, node.text)
: h('a', {
href: node.attrs?.href,
target: node.attrs?.target,
}, node.text)
},
// Custom code block component example:
[BlockTypes.CODE_BLOCK]: (node: Node) => {
return h(CodeBlock, {
class: node?.attrs?.class,
}, node.children)
},
}
</script>
<template>
<StoryblokRichText :doc="blok.articleContent" :resolvers="resolvers" />
</template>
```
If you want to use the `useStoryblokRichText` composable, you can pass the `resolvers` via the options object:
```html
<script setup>
import { type VNode, h } from "vue";
import { useStoryblokRichText, BlockTypes, MarkTypes, type StoryblokRichTextNode } from "@storyblok/vue";
import { RouterLink } from "vue-router";
const resolvers = {
// RouterLink example:
[MarkTypes.LINK]: (node: StoryblokRichTextNode<VNode>) => {
return node.attrs?.linktype === 'STORY'
? h(RouterLink, {
to: node.attrs?.href,
target: node.attrs?.target,
}, node.text)
: h('a', {
href: node.attrs?.href,
target: node.attrs?.target,
}, node.text)
},
}
const { render } = useStoryblokRichText({
resolvers,
})
const root = () => render(blok.articleContent);
</script>
<template>
<root />
</template>
```
### Legacy Rich Text Resolver
> [!WARNING]
> The legacy `richTextResolver` is soon to be deprecated. We recommend migrating to the new approach described above instead.
You can easily render rich text by using the `renderRichText` function that comes with `@storyblok/vue` and a Vue computed property:
```html
<template>
<div v-html="articleContent"></div>
</template>
<script setup>
import { computed } from "vue";
import { renderRichText } from "@storyblok/vue";
const articleContent = computed(() => renderRichText(blok.articleContent));
</script>
```
You can set a **custom Schema and component resolver globally** at init time by using the `richText` init option:
```js
import { RichTextSchema, StoryblokVue } from "@storyblok/vue";
import cloneDeep from "clone-deep";
const mySchema = cloneDeep(RichTextSchema); // you can make a copy of the default RichTextSchema
// ... and edit the nodes and marks, or add your own.
// Check the base RichTextSchema source here https://github.com/storyblok/storyblok-js-client/blob/master/source/schema.js
app.use(StoryblokVue, {
accessToken: "YOUR_ACCESS_TOKEN",
use: [apiPlugin],
richText: {
schema: mySchema,
resolver: (component, blok) => {
switch (component) {
case "my-custom-component":
return `<div class="my-component-class">${blok.text}</div>`;
default:
return "Resolver not defined";
}
},
},
});
```
You can also set a **custom Schema and component resolver only once** by passing the options as the second parameter to `renderRichText` function:
```js
import { renderRichText } from "@storyblok/vue";
renderRichText(blok.richTextField, {
schema: mySchema,
resolver: (component, blok) => {
switch (component) {
case "my-custom-component":
return `<div class="my-component-class">${blok.text}</div>`;
break;
default:
return `Component ${component} not found`;
}
},
});
```
## Compatibility
This plugin is for Vue 3. Thus, it supports the [same browsers as Vue 3](https://github.com/vuejs/rfcs/blob/master/active-rfcs/0038-vue3-ie11-support.md). In short: all modern browsers, dropping IE support.
Expand Down

0 comments on commit 5282259

Please sign in to comment.