NEWS · July 15th 2021

Documents Pane Plugin: GROQ query results inside View Pane

Check out the Documents Pane plugin that allows you to see any query results right within your Studio.

Kapehe

Kapehe is a Developer Relations Specialist at Sanity.

Ever needed to show editors a list of documents next to where they are working? The new Documents Pane has you covered. Use it for listing things like incoming references, image asset data like size or color palette, or list other documents within the same category.

Created by Simeon Griggs, the Documents Pane plugin can be found on the Sanity Exchange under Tools & Plugins..

What is Documents Pane?

When on an editable view in your Studio, the Documents Pane plugin will show the results from any GROQ query you declare within your desk view. In this guide, we'll look at a query that pulls out all the references to a certain document.

When in the Studio, an "Incoming References" tab will show a list of items for all the referenced items:

Let's break this down. We are in the editor for "Gummy Worms" which is one of the Products within this Studio's Content Lake. By clicking on "Incoming References", a new pane pops up to the side and displays all the incoming references for that particular document. In this case, Gummy Worms is being referenced on the Home Page and in 2021's Best Candy.

Installing the Plugin

To get this plugin into your own Studio, navigate to the project and run the following command:

sanity install documents-pane


Once added, you'll need to navigate to where your Structure Builder is within your code. Generally, it will be named deskStructure.js. If you have not done that within your project, check out this introduction to Structure Builders to get started.

For this particular plugin, we will need the Component inside of a View.

Once you are in your Structure Builder file, navigate to your views and add in the following code:

// ./src/deskStructure.js
import DocumentsPane from 'sanity-plugin-documents-pane'

// ...all other list items

S.view
  .component(DocumentsPane)
  .options({
    query: `*[!(_id in path("drafts.**")) && references($id)]`,
    params: { id: `_id` },
    useDraft: false
  })
  .title('Incoming References')

If we take a look at .options(), that configuration works as follows:

  • query (string, required). The current query will be filtering down to everything that is not a draft and has a reference id.
  • params (object, optional) A dot-notated string from the document object to a field, to use as variables in the query. This code is pulling out the id.
  • useDraft (boolean, optional, default: false) When populating the params values, it will use the published version of the document by default. This one doesn't want drafts so it is false.

Protip

If you’re not sure why your GROQ query has returned empty — or you’d like to see what parameters were passed into the query, set debug: true and both will be displayed if there are any errors or no results.

Referencing from the Studio

This plugin is very helpful when you are in your Studio's desk view and don't want to jump over to your Vision plugin or look at the parsed JSON version of your document. Have your views side-by-side so you know exactly what is being returned in your GROQ query of choice.

Keep all your query results at your fingertips!