Drag-and-drop Document Ordering without leaving the Editing surface
npm install @sanity/orderable-document-list> For the v2 version, please refer to the v2-branch.
Drag-and-drop Document Ordering without leaving the Editing surface.
This plugin aims to be OS-like in that you can select and move multiple documents by holding shift and clicking a second item, and toggling on/off selections by holding command/control.
A Sanity Studio with Desk Structure configured:
``ts
import {defineConfig} from 'sanity'
import {structureTool, StructureBuilder} from 'sanity/structure'
export default defineConfig({
//...
plugins: [
structureTool({
structure: (S, context) => {
/ Structure code /
},
}),
],
})
`
Run the following command in your studio directory
`sh`
npm install --save @sanity/orderable-document-list
or
`sh`
yarn add @sanity/orderable-document-list
The config parameter requires type, S and context. It also accepts title, icon, filter and params.S and context are available in desk-tool structure callback, and should be forwarded as is:
`ts
import {defineConfig} from 'sanity'
import {structureTool, StructureBuilder} from 'sanity/structure'
import {orderableDocumentListDeskItem} from '@sanity/orderable-document-list'
export default defineConfig({
//...
plugins: [
structureTool({
structure: (S, context) => {
return S.list()
.title('Content')
.items([
// Minimum required configuration
orderableDocumentListDeskItem({type: 'category', S, context}),
// Optional configuration
orderableDocumentListDeskItem({
type: 'project',
title: 'Projects',
icon: Paint,
// Required if using multiple lists of the same 'type'
id: 'orderable-en-projects',
// See notes on adding a filter below__i18n_lang == $lang
filter: ,S.menuItem()
params: {
lang: 'en_US',
},
createIntent: false, // do not add an option for item creation
menuItems: [], // allow an array of to be injected to orderable document list menu
// pass from the structure callback params above
S,
context,
}),
// ... all other desk items, e.g. all other document types not already included
// @see https://www.sanity.io/docs/studio/structure-builder-cheat-sheet#k4eb3b1891dc2
...S.documentTypeListItems().filter((item) => !(['category', 'project'].includes(item.getId())))
])
},
}),
],
})
`
Caution: Adding a filter
By default, the plugin will display _all_ documents of the same type. However, you may wish to add a filter to reduce this down to a subset of documents. A typical usecase is for internationalized document schema to order documents of just the base language version.
However, order ranks are still computed based on _all_ documents of the same type. Creating multiple lists with different filter settings could produce unexpected results.
You must pass in the type of the schema and the schema context, to create an initialValue value.
Context is available in the schema callback, and should be forwarded as is.
Additionally, pass in overrides for the field, such as making it visible by passing hidden: false.
You cannot override the name, type or initialValue attributes.
You can configure the placement of new documents by setting newItemPosition to before (defaults to after).
`js
// sanity.config.js
import {defineConfig} from "sanity";
import {structureTool, StructureBuilder} from "sanity/structure";
import {orderRankField, orderRankOrdering} from '@sanity/orderable-document-list'
export default defineConfig({
//...
plugins: [
structureTool({structure: (S, context) => {/ snip /}})
],
schema: {
types: (previousTypes) => {
return [
...previousTypes,
{
name: "category",
title: "Category",
type: "document",
// Optional: The plugin also exports a set of 'orderings' for use in other Document Lists
// https://www.sanity.io/docs/sort-orders
orderings: [orderRankOrdering],
fields: [
// Minimum required configuration
orderRankField({ type: "category" }),
// OR placing new documents on top
orderRankField({ type: "category", newItemPosition: "before" }),
// OR you can override _some_ of the field settings
orderRankField({ type: "category", hidden: false }),
// ...all other fields
],
},
]
}
}
}
`
On first load, your Document list will not have any Order. You can select "Reset Order" from the menu in the top right of the list.
You can also re-run this at any time.
The orderRankField will query the last/first Document to set an initialValue to come after/before it.newItemPosition
The placement of new documents can be configured by on the orderRankField in the document.
Now when writing a GROQ Query for Documents, use the orderRank field value to return ordered results:
`groq`
*[_type == "category"]|order(orderRank)
If fetching documents using the document-internationalization plugin, you may want to sort by the rank of the base document when the document is not in the base language, so all locales share the same order. When changing the order of documents using this plugin, the orderRank field of documents in alternate locales won't be updated. The query below ensures a consistent order for documents in the base language and in alternate languages.
`groq`
*[_type == "category" && __i18n_lang == $lang]|order(coalesce(__i18n_base->orderRank, orderRank))
To get this first version out the door there are few configuration settings and a lot of opinions. Such as:
- The name of the orderRank field is constanttype
- The ability to only sort across _all_ Documents of a
Feedback and PRs welcome :)
orderableDocumentListDeskItem` requires context from sanity config now.
See the examples above.
Uses kvandakes's TypeScript implementation of Jira's Lexorank to create a "lexographical" Document order.
Put simply it updates the position of an individual – or many – Documents in an ordered list without updating any others. It's fast.
To run this plugin locally and develop, it uses the internal test studio used by the Development teams. You need to run install and npm run dev and you will have a clear and easy example to use.
This plugin uses @sanity/plugin-kit
with default configuration for build & watch scripts.
See Testing a plugin in Sanity Studio
on how to run this plugin with hotreload in the studio.
Run "CI & Release" workflow.
Make sure to select the v3 branch and check "Release new version".
Semantic release will only release on configured branches, so it is safe to run release on any branch.
MIT © Sanity.io