Visual Builder queries

7 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.

Graph schema

A composition is a structure of CompositionNode instances.

CompositionNode

CompositionNode is the base type for nodes in the composition structure. The Optimizely GraphOptimizely 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. Available types: outline and grid.
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. An experience composition contains a list of sections. A 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 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 queriesRecursive 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
      }
    }
  }
}