Docs Developer Site
Developer Docs Guillotine - Headless GraphQL API 9.x Usage Scope and site

Scope and site

Contents

The scopeKey argument on guillotine selects the scope of a query within the current project: the content that page URLs are relative to, usually a site. Use it to resolve paths relative to that content and to retrieve its site. The scope, getSite and the path placeholders are Portal API extensions.

Project and branch select the content repository and version of the content. The scope is a separate choice within that project. See Project and branch for how these are selected.

Select a scope

Set scopeKey to the content ID or path of a site, or of another content, within the project. This example selects the site /my-site and retrieves its display name:

{
  guillotine(project: "myproject", branch: "master", scopeKey: "/my-site") {
    getSite {
      _id
      displayName
    }
  }
}

Replace myproject and /my-site with an existing project and site. The selected content must exist in the branch you query. Send this query using the request format on the Usage page.

getSite returns the nearest site at or above the selected content: the site itself when scopeKey names a site.

Path placeholders

Use ${scope} in a content key to insert the path of the content scopeKey names, and ${site} to insert the path of its site. This lets a query use paths below them without repeating their location:

{
  guillotine(project: "myproject", branch: "master", scopeKey: "/my-site/blog") {
    get(key: "${scope}") {
      displayName
    }
    getChildren(key: "${site}/persons", first: 10) {
      displayName
    }
  }
}

Here ${scope} is /my-site/blog and ${site} is /my-site. When scopeKey names a site, both are its path. Without scopeKey, or with scopeKey: "/", the project is the root and both are empty: ${site}/persons becomes /persons, and ${site} alone becomes /. ${site} is also empty for a content outside any site.

The placeholders can be used in the key argument of get, getChildren, getChildrenConnection and getPermissions. See HeadlessCms for the field signatures.

${scope} and ${site} are Guillotine placeholders inside a GraphQL string. When writing the query in a JavaScript template literal, escape them as \${scope} and \${site} so JavaScript sends the placeholders unchanged.

Relative paths

Select pageUrl.path to retrieve the path relative to the content scopeKey names, or to the project without scopeKey:

{
  guillotine(project: "myproject", branch: "master", scopeKey: "/my-site") {
    getChildren(key: "${site}/persons", first: 10) {
      displayName
      pageUrl {
        path
      }
    }
  }
}

The content’s _path field contains its path within the project. Use pageUrl.path for site-relative links, adapt it to your frontend’s routing, and append pageUrl.queryString if requested. See Images and URLs.

Project root and URL context

Without scopeKey, the project root is the context for paths and URLs, as with scopeKey: "/": ${scope} and ${site} are empty, page URLs carry the full content path, and pageUrl.baseUrl is the Base URL configured for the project. The project root is not a site content item, so getSite returns null in both cases, and env.localContext.scopeKey is only present when scopeKey is given.

Selecting a scope does not restrict every query to its descendants: queryDsl still searches the project, and an absolute content path can point outside the scope. When building links across sites, choose the appropriate scope and frontend route for each target. See Base URLs for nested sites and path context.

Contents

Contents