Migrating plugins to support content releases
Guide to support content releases and perspectives in studio plugins
The introduction of Content Releases into Sanity Studio introduces some new core concepts available through the Sanity SDK.
To interface with the studio global perspective, usePerspective is available. This hook must be used within Studio. For example:
import { usePerspective } from 'sanity'
function MyComponent() {
const { perspectiveStack } = usePerspective()
// ...
}usePerspective returns:
/* The selected perspective name, it could be a release or Published */
selectedPerspectiveName: 'published' | ReleaseId | undefined
/**
* The releaseId as `r<string>``; it will be undefined
* if the selected perspective is `published` or `drafts`
*/
selectedReleaseId: ReleaseId | undefined
/* Return the current global release */
selectedPerspective: SelectedPerspective
/**
* The stacked array of releases ids ordered chronologically
* to represent the state of documents at the given point in time.
*/
perspectiveStack: PerspectiveStack
/* The excluded perspectives */
excludedPerspectives: string[]Further, a ReleaseId may be used to query document versions within a release as noted here.
There are particular concerns relevant for plugins which make custom input components available via custom input types. Prior to Content Releases, a document form may have made its form inputs read only in instances where data was loading, being re-synced, or in a transient state. Now, Studio Perspectives allow users to view the document form of the published document version. This form is read only in all instances, besides liveEdit. In these cases it is imperative that plugins pass the readOnly prop available when rendering custom components:
const PluginComponent = ({ readOnly }: InputProps) => {
... spread `readOnly` if using Sanity UI, or use `readOnly` to control disabling input ...
}
export const plugin = defineType({
...,
fields: [
...,
{
...,
components: {
input: PluginComponent
}
]
})