|
1 | | -# sanity-blocks-vue-component |
2 | | - |
3 | | -A Vue component for rendering [block text](https://www.sanity.io/docs/schema-types/block-type) from [Sanity](https://www.sanity.io/). Allows you to pass other Vue components as custom serializers. |
4 | | - |
5 | | -## Contents |
6 | | - |
7 | | -- [Installing](#installing) |
8 | | -- [Basic Usage](#basic-usage) |
9 | | -- [Props](#props) |
10 | | -- [Serializer Property](#serializer-property) |
11 | | -- [Component Serializers](#component-serializers) |
12 | | -- [Full Example](#full-example) |
13 | | -- [Credits](#credits) |
14 | | -- [License](#license) |
15 | | - |
16 | | -## Installing |
17 | | - |
18 | | -### via npm |
19 | | - |
| 1 | +<div align="center"> |
| 2 | + <h1>Sanity Blocks Vue Component</h1> |
| 3 | + <p> |
| 4 | + <img alt="NPM version" src="https://img.shields.io/npm/v/sanity-blocks-vue-component?color=000&style=flat-square"> |
| 5 | + <img alt="NPM downloads" src="https://img.shields.io/npm/dm/sanity-blocks-vue-component?color=000&style=flat-square"> |
| 6 | + <img alt="GitHub Release Date" src="https://img.shields.io/github/release-date/rdunk/sanity-blocks-vue-component?color=000&style=flat-square"> |
| 7 | + <img alt="Vue version" src="https://img.shields.io/npm/dependency-version/sanity-blocks-vue-component/vue?color=000&style=flat-square"> |
| 8 | + <img alt="License" src="https://img.shields.io/npm/l/sanity-blocks-vue-component.svg?color=000&style=flat-square"> |
| 9 | + </p> |
| 10 | + </p> |
| 11 | + <p> |
| 12 | + <h3>A Vue component for rendering <a href="https://www.sanity.io/docs/block-content" _target="blank">block content</a> from Sanity.</h3> |
| 13 | + <br> |
| 14 | + <br> |
| 15 | +</div> |
| 16 | + |
| 17 | +## Install |
| 18 | + |
| 19 | +> **Notice**: This version is a complete rewrite for Vue 3. For Vue 2, see versions <1.0.0. |
| 20 | +
|
| 21 | +```bash |
| 22 | +$ npm i sanity-blocks-vue-component # or yarn add sanity-blocks-vue-component |
20 | 23 | ``` |
21 | | -npm install --save sanity-blocks-vue-component |
22 | | -``` |
23 | | - |
24 | | -### Add Component Globally |
25 | 24 |
|
26 | | -```js |
27 | | -import BlockContent from 'sanity-blocks-vue-component' |
28 | | -Vue.component('block-content', BlockContent); |
29 | | -``` |
| 25 | +## Usage |
30 | 26 |
|
31 | | -## Basic Usage |
| 27 | +Import directly into your component or view: |
32 | 28 |
|
33 | | -Basic usage in a single file component, see the [full example](#full-example) below for more detail. |
34 | | - |
35 | | -```html |
| 29 | +```vue |
36 | 30 | <template> |
37 | | - <block-content |
38 | | - :blocks="blocks" |
39 | | - :serializers="serializers" |
40 | | - /> |
| 31 | + <SanityBlocks :blocks="blocks" :serializers="serializers" /> |
41 | 32 | </template> |
42 | 33 |
|
43 | 34 | <script> |
44 | | -import MyComponent from 'MyComponent.vue' |
| 35 | +import { SanityBlocks } from 'sanity-blocks-vue-component'; |
| 36 | +import CustomComponent from 'CustomComponent.vue'; |
45 | 37 |
|
46 | 38 | export default { |
47 | | - data() { |
48 | | - return { |
49 | | - blocks : [...], // Sanity block text |
50 | | - serializers: { |
51 | | - types: { |
52 | | - foo: MyComponent |
53 | | - } |
54 | | - } |
| 39 | + components: { SanityBlocks }, |
| 40 | + setup() { |
| 41 | + const blocks = [...]; // Sanity block text |
| 42 | + const serializers = { |
| 43 | + types: { |
| 44 | + custom: CustomComponent, |
| 45 | + }, |
55 | 46 | }; |
| 47 | + return { blocks, serializers }; |
56 | 48 | } |
57 | | -}; |
| 49 | +} |
58 | 50 | </script> |
59 | 51 | ``` |
60 | 52 |
|
61 | | -## Props |
62 | | - |
63 | | -The following props can be passed to the component. |
64 | | - |
65 | | -|Prop|Required|Description|Type| |
66 | | -|:---|---|---|---| |
67 | | -|`blocks`|Yes|Block text retreived from Sanity.|Array, Object| |
68 | | -|`serializers`|No|Any required custom serializers, see below for more detail.|Object| |
69 | | -|`className`|No|The class applied to any container element if present. Ignored if a custom container serializer is passed.|String| |
70 | | -|`projectId`|No|ID of the Sanity project.|String| |
71 | | -|`dataset`|No|Name of the Sanity dataset containing the document that is being rendered.|String| |
72 | | -|`imageOptions`|No|Query parameters to apply in image blocks to control size/crop mode etc.|Object| |
73 | | -|`renderContainerOnSingleChild`|No|Set true to enforce a container element for single block input data.|Boolean| |
74 | | - |
75 | | -## Serializer Property |
76 | | - |
77 | | -Serializers are the functions used for rendering block content. They can be defined either as a string (e.g. `div`) or as a Vue Component (see below for more detail). This package comes with default serializers that will work for rendering basic block content, but you may pass a `serializer` prop to override or extend the default serializers. The object passed will be merged with the default serializers object. |
78 | | - |
79 | | -|Property|Description| |
80 | | -|:---|---| |
81 | | -|`types`|Object of serializers for block types.| |
82 | | -|`marks`|Object of serializers for marks.| |
83 | | -|`list`|Serializer for list containers.| |
84 | | -|`listItem`|Serializer for list items.| |
85 | | -|`hardBreak`|Serializer for hard breaks.| |
86 | | -|`container`|Serializer for the element used to wrap the blocks.| |
87 | | - |
88 | | -## Component Serializers |
89 | | - |
90 | | -### For Blocks |
91 | | -When using custom Vue components as block serializers, all properties of the block object will be passed via [`v-bind`](https://vuejs.org/v2/api/#v-bind). **To access the data, define the corresponding [props](https://vuejs.org/v2/guide/components-props.html) in your component**. Components will also be passed a `_sanityProps` prop which is an object with two properties: |
92 | | - |
93 | | -- `node` - the block data object. |
94 | | -- `options` - Sanity specific options (`projectId`, `dataset`, `imageOptions`) passed to the root component. |
95 | | - |
96 | | -This additional prop can be useful for generating image URLs using the [@sanity/image-url](https://github.com/sanity-io/sanity/tree/next/packages/%40sanity/image-url) package. |
97 | | - |
98 | | -### For Marks |
99 | | -When using custom Vue components as mark serializers, all properties of the block object will be passed via [`v-bind`](https://vuejs.org/v2/api/#v-bind). **To access the data, define the corresponding [props](https://vuejs.org/v2/guide/components-props.html) in your component**. You can use [slots](https://vuejs.org/v2/guide/components-slots.html) (e.g. `this.$slots.default`) to access the mark text or content. |
| 53 | +Or install globally: |
100 | 54 |
|
101 | | -#### Functional Components |
102 | | -If your mark serializer is purely presentational (no reactive data, no lifecycle methods), you may want to use a [functional component](https://vuejs.org/v2/guide/render-function.html#Functional-Components) instead for better performance. When using functional components, you can access the properties on the `props` object. |
| 55 | +```ts |
| 56 | +import { createApp } from 'vue'; |
| 57 | +import { SanityBlocks } from 'sanity-blocks-vue-component'; |
| 58 | +import App from './App.vue'; |
103 | 59 |
|
104 | | -For example, simple external links are a good candidate for a functional component: |
105 | | -```html |
106 | | -<template functional> |
107 | | - <a :href="props.href" |
108 | | - target="_blank" |
109 | | - rel="noopener"> |
110 | | - <slot /> |
111 | | - </a> |
112 | | -</template> |
| 60 | +const app = createApp(App); |
| 61 | +app.component('sanity-blocks', SanityBlocks); |
| 62 | +app.mount('#app'); |
113 | 63 | ``` |
114 | 64 |
|
115 | | -## Full Example |
| 65 | +## Props |
116 | 66 |
|
117 | | -#### MainComponent.vue |
| 67 | +The following props can be passed to the component. |
118 | 68 |
|
119 | | -```html |
120 | | -<template> |
121 | | - <block-content |
122 | | - :blocks="blocks" |
123 | | - :serializers="serializers" |
124 | | - /> |
125 | | -</template> |
| 69 | +| Prop | Required | Description | Type | |
| 70 | +| ------------- | -------- | -------------------------------------------------- | ------ | |
| 71 | +| `blocks` | Yes | Block content retrieved from Sanity. | Array | |
| 72 | +| `serializers` | No | Any custom serializers you want to use. See below. | Object | |
126 | 73 |
|
127 | | -<script> |
128 | | -// Import the component if not already added globally |
129 | | -import BlockContent from 'sanity-blocks-vue-component' |
130 | | -// Import any components to be used as serializers |
131 | | -import GreetingComponent from 'GreetingComponent.vue' |
| 74 | +## Serializers |
132 | 75 |
|
133 | | -export default { |
134 | | - components: { |
135 | | - BlockContent |
136 | | - }, |
137 | | - data() { |
138 | | - return { |
139 | | - // The block data will usually be retrieved from Sanity |
140 | | - blocks: [ |
141 | | - { |
142 | | - _type: 'greeting', // Sanity specific prop, corresponds to the serializer name |
143 | | - _key: 'example', // Sanity specific prop |
144 | | - firstname: 'Foobert', // Example custom property for this block type |
145 | | - lastname: 'Barson', // Example custom property for this block type |
146 | | - } |
147 | | - ], |
148 | | - serializers: { |
149 | | - types: { |
150 | | - greeting: GreetingComponent |
151 | | - } |
152 | | - } |
153 | | - }; |
154 | | - } |
155 | | -}; |
156 | | -</script> |
157 | | -``` |
| 76 | +Serializers are the functions used for rendering block content. They can be defined as a string or a Vue Component. This package comes with default serializers for rendering basic block content, you can pass a `serializer` prop to override or extend the defaults. |
158 | 77 |
|
159 | | -##### GreetingComponent.vue |
160 | | -```html |
161 | | -<template> |
162 | | - <div>Hello, {{ firstname }} {{ lastname }}.</div> |
163 | | -</template> |
| 78 | +| Property | Description | |
| 79 | +| ----------- | -------------------------------------- | |
| 80 | +| `types` | Object of serializers for block types. | |
| 81 | +| `marks` | Object of serializers for marks. | |
| 82 | +| `styles` | Object of serializers for styles. | |
| 83 | +| `list` | Serializer for list containers. | |
| 84 | +| `listItem` | Serializer for list items. | |
| 85 | +| `hardBreak` | Serializer for hard breaks. | |
164 | 86 |
|
165 | | -<script> |
166 | | -export default { |
167 | | - // Define the block object properties this component receives as props |
168 | | - props: { |
169 | | - firstname: { |
170 | | - type: String, |
171 | | - }, |
172 | | - lastname: { |
173 | | - type: String, |
174 | | - } |
175 | | - }, |
176 | | -} |
177 | | -</script> |
178 | | -``` |
| 87 | +## Component Serializers |
| 88 | + |
| 89 | +The most common use case is defining serializers for custom block types and marks, using the `types` and `marks` serializer properties. For example, if you have a block of type `custom`, you can add a property to the `serializers.types` object with the key `custom` and a value of the Vue component that should serialize blocks of that type. |
179 | 90 |
|
180 | | -## Credits |
| 91 | +When using a custom Vue component as a serializer, all properties of the block or mark object (excluding `_key` and `_type`) will be passed as [props](https://v3.vuejs.org/guide/component-props.html). |
181 | 92 |
|
182 | | -Relies heavily on the official Sanity [block-content-to-hyperscript](https://github.com/sanity-io/block-content-to-hyperscript) package. |
| 93 | +> **To access the data, you should define the correpsonding props in your component.** |
183 | 94 |
|
| 95 | +For mark serializers, you can also use [slots](https://v3.vuejs.org/guide/component-slots.html) to access the mark text or content. |
184 | 96 |
|
185 | 97 | ## License |
186 | 98 |
|
|
0 commit comments