Visual Builder queries

8 min

Visual Builder is a way of composing content and layout. See Visual Builder for information. When an experience is indexed in Optimizely, the layout and the data parts are merged into a composition model.

An experience content type can have more than one composition: the built-in composition and any number of custom composition properties. CMS (SaaS) indexes each one as its own field, and each field uses the schema in the following sections. See Composition properties.

Graph schema

A composition is a structure of CompositionNode instances.

CompositionNode

CompositionNode is the base type for nodes in the composition structure. The Optimizely Graph schema for CompositionNode is defined as:

Field	Type	Description
type	String	The node content type, if the node has a corresponding content type. Example types: BlankExperience , BlankSection, ImageElement, TextElement.
nodeType	String	The node type. Available types: experience , section, row, column, and component.
layoutType	String	The layout type. The default types are outline and grid. Add-ons can make more layout types available.
displayName	String	The name of the node.
key	String	A unique key for the node within the composition. Typically used for marking up live preview attributes. See Enable live preview.
displayTemplateKey	String	Optional key specifying which Display Template is used by the node (if any).
displaySettings	[CompositionDisplaySetting]	An array of display settings that are defined for the node.

CompositionStructureNode

A subtype of CompositionNode that represents a structural node in the composition structure. The Optimizely Graph schema for CompositionStructureNode is defined as the following:

Field	Type	Description
nodes	[CompositionNode]	The children nodes to the current node.
component	_IComponent	The associated data for section nodes. For structure nodes like row and column, the component is null.

CompositionComponentNode

A subtype to CompositionNode that contains a VisualBuilder component. The Optimizely Graph schema for CompositionComponentNode is defined as the following:

Field	Type	Description
component	_IComponent	The component instance used. It can be cast to a specific component based on content type, like ImageElement, TextElement, and so on.

CompositionDisplaySetting

Represents a display setting value for a composition node. The Optimizely Graph schema for CompositionDisplaySetting is defined as the following:

Field	Type	Description
key	String	The key for the display setting. Should match a key defined in the corresponding Display Template.
value	String	The value for the display setting. Available values are defined in the corresponding Display Template.

Explicit query

Content types based on Experience and Section have a property composition that contains the merged structure from the defined layout and data for the Visual Builder output. With the default layout types, an experience composition contains a list of sections. Each section is grid-based and consists of rows, where each row has columns and each column has components. Given that structural knowledge, a query to get a composition can be specified as the following:

query ExplicitExperienceQuery {
  _Experience {
    items {
      composition {
        displayName
        displaySettings {
          key
          value
        }
        displayTemplateKey
        key
        nodeType
        nodes {
          displayName
          displaySettings {
            key
            value
          }
          displayTemplateKey
          key
          nodeType
          type
          ... on CompositionStructureNode {
            displayName
            displayTemplateKey
            key
            nodeType
            component {
              ...compositionComponent
            }
            nodes {
              displayName
              displaySettings {
                key
                value
              }
              displayTemplateKey
              key
              nodeType
              type
              ... on CompositionStructureNode {
                displayName
                displaySettings {
                  key
                  value
                }
                displayTemplateKey
                key
                nodeType
                type
                nodes {
                  displayName
                  displaySettings {
                    key
                    value
                  }
                  displayTemplateKey
                  key
                  nodeType
                  type
                  ... on CompositionStructureNode {
                    displayName
                    displaySettings {
                      key
                      value
                    }
                    displayTemplateKey
                    key
                    nodeType
                    type
                    nodes {
                      displayName
                      displaySettings {
                        key
                        value
                      }
                      displayTemplateKey
                      key
                      nodeType
                      type
                      ... on CompositionComponentNode {
                        displayName
                        displaySettings {
                          key
                          value
                        }
                        displayTemplateKey
                        key
                        nodeType
                        type
                        component {
                          ...compositionComponent
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}

fragment compositionComponent on _IComponent {
  ... on DescriptiveSection {
    Description
  }
  ... on HeadingElement {
    Heading: Body
  }
  ... on RichTextElement {
    Body {
      json
    }
  }
  ... on ImageElement {
    AltText
    Image {
      url {
        default
      }
    }
  }
}

Recursive query

The previous explicit query is repetitive because you query for a structure node in a fixed number of nested levels (given that you know that the default structure of an experience is experience/section/row/column/component). For each level, you query for all available values (type, nodetype, displaySettings, and so on). An alternative is to write a recursive query. See Recursive queries in the Optimizely Graph documentation for information. The analogous recursive query to the explicit query above is:

query RecursiveExperienceQuery {
  _Experience {
    items {
      composition {
        ...structureNode
      }
    }
  }
}

fragment structureNode on ICompositionNode {
  ... on CompositionStructureNode {
    key
    displayName
    type
    nodeType
    displayTemplateKey
    displaySettings {
      key
      value
    }
    component {
      ...compositionComponent
    }
    nodes @recursive {
      type
    }
  }
  ... on CompositionComponentNode {
    key
    displayName
    type
    nodeType
    displayTemplateKey
    displaySettings {
      key
      value
    }
    component {
      ...compositionComponent
    }
  }
}

fragment compositionComponent on _IComponent {
  ... on DescriptiveSection {
    Description
  }
  ... on HeadingElement {
    Heading: Body
  }
  ... on RichTextElement {
    Body {
      json
    }
  }
  ... on ImageElement {
    AltText
    Image {
      url {
        default
      }
    }
  }
}

Query a custom composition property

An experience content type can declare extra composition properties in addition to the built-in composition. CMS (SaaS) indexes each one as a field named after the property key. The field has the type CompositionStructureNode, the same type as composition. Because the schema is identical, the same fragments work for a custom composition. Select it alongside the built-in composition in one query.

Graph field names match the property key exactly, including case. For example, query a property with the key sidebar as sidebar. The following query fetches the built-in composition and a custom sidebar composition from a LandingPage experience. It reuses the structureNode and compositionComponent fragments from the recursive query.

query LandingPageCompositionsQuery {
  LandingPage {
    items {
      composition {
        ...structureNode
      }
      sidebar {
        ...structureNode
      }
    }
  }
}

The compositions are independent, so a query for one composition does not return components from the other. The built-in composition is always present. When the experience has no layout, it returns an empty structure node. CMS (SaaS) does not index a custom composition property that has no value, so the field returns null.

The root node of a custom composition reflects the content that owns it, so its nodeType is experience. Its layoutType is the layout configured for that property, which can differ from the layout of the built-in composition. A composition with the grid layout type holds row nodes directly under its root, without an intermediate section node.