Layout query and response

Building the query

The following GraphQL query lets you retrieve the complete layout data (page representation) for a page by its path. Note that you need to specify the language version of the page and the site that contains the page. This is one of the most common queries you'll make to render content.

query {
  layout(site:"my-site" language:"en" routePath:"/") {
    item {
      rendered # Returns layout data
    }
  }
}

Making the query

The following pseudo-code describes making the query directly from your app. You can adapt this query to your own framework or complete the Render SitecoreAI content in your app walkthrough for complete code examples.

function fetchLayoutData(site, language, routePath):
    endpoint = ENV.SITECORE_EDGE_PLATFORM_URL
    contextId = ENV.SITECORE_EDGE_CONTEXT_ID

    query = """
      query {
        layout(site: "{site}" language: "{language}" routePath: "{routePath}") {
          item {
            rendered
          }
        }
      }
    """

    headers = {
      "Content-Type": "application/json",
      "x-sitecore-contextid": contextId
    }

    response = HTTP_POST(endpoint, { query }, headers)
    result = PARSE_JSON(response.body)

    if result.errors:
        throw result.errors

    rendered = result.data.layout.item.rendered
    return (rendered is string) ? PARSE_JSON(rendered) : rendered

Note the following about the script:

• The endpoint and Context ID are stored as environment variables.
• The Context ID is included in the x-sitecore-contextid request header.
• The query requires that you specify the site the page belongs to, the language version of the page, and the path to the page. This lets you control which page to retrieve layout data for. For example, the "ja-JP" language version of the "/products" page of your "example-site".
• In the query, layout.item.rendered returns the layout data.
• The response is JSON, which your app needs to parse.

Understanding the response

When you make the request described in the previous section, Sitecore returns a JSON object, which looks similar to the following:

{
  "data": {
    "layout": {
      "item": {
        "rendered": {
          "sitecore": {
            "context": {
              "pageEditing": false,
              "site": { "name": "<YOUR_SITE_NAME>" },
              "pageState": "normal",
              "editMode": "chromes",
              "language": "<YOUR_SITE_LANGUAGE_CODE>",
              "itemPath": "/"
            },
            "route": {
              "name": "Home",
              "displayName": "Home",
              "fields": {
                /* Page-level content fields (title, summary, thumbnail, keywords, navigation information, etc.) */
              },
              "placeholders": {
                "headless-header": [ /* Array of components for page header */ ],
                "headless-main": [ /* Array of components for page main section */ ],
                "headless-footer": [ /* Array of components for page footer */ ]
              }
            }
          }
        }
      }
    }
  }
}

The sitecore root-level object contains metadata, information about the route, page-level content fields, and a placeholders object:

• sitecore.context - provides metadata about the current page request, such as the path of the current item, the name of the site, and whether the page is currently being edited in the Page builder.
• sitecore.route - provides the route segment name, the display name, and page-level content fields defined on the route's Sitecore item.
• sitecore.placeholders - represents the layout tree for the page. Most sites work with the following top-level placeholders: headless-header, headless-main, and headless-footer. Each top-level placeholder contains an ordered list of components to render. Here's an example component from headless-main, which represents the main section of the page:

{
  "uid": "<UNIQUE_COMPONENT_ID>",
  "componentName": "<COMPONENT_NAME>",
  "dataSource": "<DATA_SOURCE_PATH>",
  "params": { /* Display parameters (styles, modes) */ },
  "fields": { /* Content data for this component */ },
  "placeholders": {
    /* Nested children components (recursive structure) */
    "nested-placeholder-name": [ /* More components */ ]
  }
}

The properties of each component are:

• uid - a unique identifier for this component instance on the page.
• componentName - the name of the component, such as "Promo" or  "RichText". You can use this to look up the correct implementation in your component mapping.
• dataSource - the Sitecore item path or ID that provides the component's content.
• params - rendering parameters set by the content author in the Page builder, such as CSS class names, style variants, or layout options. All parameter values are strings. Use these in your implementation to apply the author's visual configuration.
• fields - the content fields used to populate the component. Where these fields come from depends on the Rendering Contents Resolver configured on the rendering item. By default, fields come from the component's datasource item, but other resolvers can source content from the context item, children of the datasource, navigation hierarchies, and more. Different field types have different JSON shapes: most fields use a simple { "value": "..." } structure, while complex types like Image and Link use an object for value. See also field types.
• placeholders - components can also contain other components, which enables nested layout structures and makes rendering recursive. If a component contains other components, those are listed in the component's own, nested placeholders object. You'll often see structural components, such as ColumnSplitter and Container, use nested placeholders. You render nested placeholders the same way you render top-level ones, by passing them to your Placeholder component.

When you render Sitecore content on your site, you programmatically query Sitecore for layout data, parse the recursive JSON in the response, and render components on your page.