11 |
12 | ## Installation
13 |
14 | ```
15 | npm install --save sanity-plugin-hotspot-array
16 | ```
17 |
18 | or
19 |
20 | ```
21 | yarn add sanity-plugin-hotspot-array
22 | ```
23 |
24 |
25 | ## Usage
26 |
27 | Add it as a plugin in sanity.config.ts (or .js):
28 |
29 | ```js
30 | import { imageHotspotArrayPlugin } from "sanity-plugin-hotspot-array";
31 |
32 | export default defineConfig({
33 | // ...
34 | plugins: [
35 | imageHotspotArrayPlugin(),
36 | ]
37 | })
38 | ```
39 |
40 | Now you will have `imageHotspot` available as an options on `array` fields:
41 |
42 | ```js
43 | import {defineType, defineField} from 'sanity'
44 |
45 | export const productSchema = defineType({
46 | name: `product`,
47 | title: `Product`,
48 | type: `document`,
49 | fields: [
50 | defineField({
51 | name: `hotspots`,
52 | type: `array`,
53 | of: [
54 | // see `Spot object` setup below
55 | ],
56 | options: {
57 | // plugin adds support for this option
58 | imageHotspot: {
59 | // see `Image and description path` setup below
60 | imagePath: `featureImage`,
61 | descriptionPath: `details`,
62 | // see `Custom tooltip` setup below
63 | tooltip: undefined,
64 | }
65 | },
66 | }),
67 | // ...all your other fields
68 | // ...of which one should be featureImage in this example
69 | ],
70 | })
71 | ```
72 | There is no need to provide an explicit input component, as that is handled by the plugin.
73 |
74 | The plugin makes a number of assumptions to add and update data in the array. Including:
75 |
76 | - The `array` field is an array of objects, with a single object type
77 | - The object contains two number fields named `x` and `y`
78 | - You'll want to save those values as % from the top left of the image
79 | - The same document contains the image you want to add hotspots to
80 |
81 | ### Image path
82 |
83 | The custom input has the current values of all fields in the document, and so can "pick" the image out of the document by its path.
84 |
85 | For example, if you want to add hotspots to an image, and that image is uploaded to the field `featuredImage`, your fields `options` would look like:
86 |
87 | ```js
88 | options: {
89 | imageHotspot: {
90 | imagePath: `featureImage`
91 | }
92 | }
93 | ```
94 |
95 | To pick the image out of the hotspot-array parent object, use
96 | ```js
97 | options: {
98 | imageHotspot: {
99 | pathRoot: 'parent'
100 | }
101 | }
102 | ```
103 |
104 | ### Description path
105 |
106 | The custom input can also pre-fill a string or text field with a description of the position of the spot to make them easier to identify.
107 | Add a path **relative to the spot object** for this field.
108 |
109 | ```js
110 | options: {
111 | imageHotspot: {
112 | descriptionPath: `details`
113 | }
114 | }
115 | ```
116 |
117 | ### Spot object
118 |
119 | Here's an example object schema complete with initial values, validation, fieldsets and a styled preview.
120 |
121 | ```js
122 | defineField({
123 | name: 'spot',
124 | type: 'object',
125 | fieldsets: [{name: 'position', options: {columns: 2}}],
126 | fields: [
127 | {name: 'details', type: 'text', rows: 2},
128 | {
129 | name: 'x',
130 | type: 'number',
131 | readOnly: true,
132 | fieldset: 'position',
133 | initialValue: 50,
134 | validation: (Rule) => Rule.required().min(0).max(100),
135 | },
136 | {
137 | name: 'y',
138 | type: 'number',
139 | readOnly: true,
140 | fieldset: 'position',
141 | initialValue: 50,
142 | validation: (Rule) => Rule.required().min(0).max(100),
143 | },
144 | ],
145 | preview: {
146 | select: {
147 | title: 'details',
148 | x: 'x',
149 | y: 'y',
150 | },
151 | prepare({title, x, y}) {
152 | return {
153 | title,
154 | subtitle: x && y ? `${x}% x ${y}%` : `No position set`,
155 | }
156 | },
157 | },
158 | })
159 | ```
160 |
161 | ## Custom tooltip
162 |
163 | You can customise the Tooltip to display any Component, which will receive `value` (the hotspot value with x and y),
164 | `schemaType` (schemaType of the hotspot value), and `renderPreview` (callback for rendering Studio preview).
165 |
166 | ### Example 1 - use default hotspot preview
167 |
168 | ```tsx
169 | import { Box } from "@sanity/ui";
170 | import { HotspotTooltipProps } from "sanity-plugin-hotspot-array";
171 |
172 | export function HotspotPreview({
173 | value,
174 | schemaType,
175 | renderPreview,
176 | }: HotspotTooltipProps) {
177 | return (
178 |
158 | {imageRect &&
159 | (value?.length ?? 0) > 0 &&
160 | value?.map((spot, index) => (
161 |
175 |
176 | 
185 |
186 |
187 |
188 | ) : (
189 | {imageHotspotOptions.imagePath}
193 |
194 | ) : (
195 | <>
196 | Define a path in this field using to the image field in this document at{' '}
197 | options.hotspotImagePath
198 |
199 | )}
200 |
181 | {/* Dot */}
182 |
198 |
195 | {index + 1}
196 |
197 |