Inline and referenced components

Dashboard

1. In the builder, add a field of type Reference and choose its Target: a component, or Any component. For an inline section, use Component or Block list instead.
2. In a page bound to that component, the Reference field is a picker: a searchable list of the documents bound to the target, title over key, with Clear beside it. A block list has Add block under it.
3. In the JSON view of any structured document, Insert component… offers both kinds, as New block (the component's fields at the cursor, with _component) and as Reference (a pointer to an existing document).
4. Open the shared document, such as the hero instance. Its Used by panel lists every document that points at it, and the field each one points from. While the list is not empty, rename and delete are unavailable, and the button gives the reason.
5. Edit it, press Save, then Publish. Before you confirm, the dialog lists the live pages that change with it.

API

This example uses the hero component and its instance components/heroes/spring-sale from Components and the builder, published. Set the variables, with a delivery key for the reads:

export QUILLET_API_URL=<cms-url> QUILLET_PROJECT=<project> QUILLET_ENV=<environment>
export QUILLET_MANAGEMENT_KEY=<keyId>:<secret>
export QUILLET_KEY_ID=<delivery-keyId> QUILLET_KEY_SECRET=<delivery-secret>
E="$QUILLET_API_URL/api/v1/projects/$QUILLET_PROJECT/envs/$QUILLET_ENV"
D="$QUILLET_API_URL/d/v1/$QUILLET_PROJECT/$QUILLET_ENV"

Write a page component with a reference slot, and two pages that point at the same hero:

curl -s -X PUT "$E/documents/_schemas/campaign" -u "$QUILLET_MANAGEMENT_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"type":"json","title":"Campaign","content":{
       "type":"object","title":"Campaign","required":["title"],"additionalProperties":false,
       "properties":{
         "title":{"type":"string"},
         "hero":{"type":"object","x-quillet":{"ref":"hero","label":"Hero"}}},
       "x-quillet":{"page":true,"preview":"title","order":["title","hero"]}}}'

curl -s -X PUT "$E/documents/pages/spring" -u "$QUILLET_MANAGEMENT_KEY" -H 'Content-Type: application/json' \
  -d '{"type":"json","schema":"campaign","title":"Spring","content":{"title":"Spring at the shop","hero":{"$ref":"components/heroes/spring-sale"}}}'

curl -s -X PUT "$E/documents/pages/autumn" -u "$QUILLET_MANAGEMENT_KEY" -H 'Content-Type: application/json' \
  -d '{"type":"json","schema":"campaign","title":"Autumn","content":{"title":"Autumn at the shop","hero":{"$ref":"components/heroes/spring-sale"}}}'

curl -s -X POST "$E/publish" -u "$QUILLET_MANAGEMENT_KEY" -H 'Content-Type: application/json' \
  -d '{"documents":[{"key":"_schemas/campaign"},{"key":"pages/spring"},{"key":"pages/autumn"}]}'

Read one page with the reference resolved, and once more as written:

curl -s -u "$QUILLET_KEY_ID:$QUILLET_KEY_SECRET" "$D/content/pages/spring"
curl -s -u "$QUILLET_KEY_ID:$QUILLET_KEY_SECRET" "$D/content/pages/spring?refs=0"

{"key":"pages/spring",…,"content":{"title":"Spring at the shop","hero":{"headline":"Spring sale",…}},
 "_meta":{…,"version":1,…,"refs":[{"path":"hero","key":"components/heroes/spring-sale","resolvedLocale":"en-US","version":1}],"assets":[]}}

Ask what uses the hero and what publishing it would change, then try to delete it:

curl -s "$E/references/components/heroes/spring-sale" -u "$QUILLET_MANAGEMENT_KEY"
curl -s "$E/publish-impact/components/heroes/spring-sale" -u "$QUILLET_MANAGEMENT_KEY"
curl -s -X DELETE "$E/documents/components/heroes/spring-sale" -u "$QUILLET_MANAGEMENT_KEY"

{"error":"in_use","message":"This document is referenced by other documents; remove those references first.",
 "usedBy":[{"key":"pages/autumn","locale":"en-US"},{"key":"pages/spring","locale":"en-US"}]}

CLI

With QUILLET_API_URL, QUILLET_PROJECT, QUILLET_ENV and QUILLET_MANAGEMENT_KEY set as in the API tab, run:

npx quillet content refs components/heroes/spring-sale
npx quillet publish components/heroes/spring-sale --impact

KEY           LOCALE  PATH
pages/autumn  en-US   hero
pages/spring  en-US   hero
pages/autumn (en-US): inlines components/heroes/spring-sale
pages/spring (en-US): inlines components/heroes/spring-sale

--impact prints what the publish would change and publishes nothing. Without it, publish prints the same lines and, at a terminal, asks before it publishes; --yes skips the question.

SDK

With the delivery key and the other settings in the environment, as in the quick start, save this as refs.mjs and run node refs.mjs:

// refs.mjs: read a page with its reference resolved, then as written.
import { quillet } from '@quilletcms/sdk/node'

const q = quillet()

const page = await q.get('pages/spring')
console.log(page.content.hero.headline)
for (const ref of page._meta.refs) {
  console.log(ref.path, ref.key, ref.missing ? 'missing' : `v${ref.version}`)
}

const asWritten = await q.get('pages/spring', { refs: 0 })
console.log(asWritten.content.hero)

Spring sale
hero components/heroes/spring-sale v1
{ '$ref': 'components/heroes/spring-sale' }

refs can also be set once for the client, in its configuration. The generated Ref<T> type describes the field both ways; see Generated types.