loading table of contents...

Headless Server Developer Manual / Version 2310

Table Of Contents

4.15 Viewtypes


When rendering a content item, different information may be used to display. For example, a collection could be displayed as a simple list, or as teasers with picture and details. To control the different variants, several content types have a viewtype property containing a layout variant.

To define a query for a subset of fields, that are needed for rendering, the viewtype property of a content item needs to be considered in the query. This applies not only for a subset of the top level fields, but also for fields of linked contents.

Clients can already formulate conditional queries depending on the viewtype, but these queries can become overly complex and hard to handle. The default approach, to always retrieve all fields, leads to overfetching.

To be able to pose precise queries and only retrieve the required fields, a viewtype specific type is needed. This viewtype specific type can be defined in the GraphQL schema by adding a new type, that is marked with the annotation @viewtype.

Example: A collection that is viewtype specific for viewtype hero:

type ViewTypeHeroCollection implements CMCollection @inherit(from: ["CMCollectionImpl"]) @viewtype(name: "hero") {}

The @viewtype annotation takes the name of the viewtype as argument and can be defined for object types:

directive @viewtype(
  name: String!

Now the client can pose viewtype specific queries:

  content {
    content(id: "1234") {
      ... on CMCollection {
      ... on ViewTypeHeroCollection {
        items {
          ... on CMTeasable {
            pictures {

Serverside, the viewtype specific types are resolved by a PostProcessor, that evaluates the annotation and returns the specific type instead of the default type.

Supported types

The viewtype annotation is supported for the types

  • CMCollection
  • PageGridPlacement

The viewtype specific types ViewTypeHeroPageGridPlacement and ViewTypeHeroCollection for layout variant hero are already available in the Blueprint

To define a new viewtype specific type, follow these steps:

  • Add a new type, that implements one of the supported interfaces PageGridPlacement or CMCollection.
  • Add the annotation @viewtype to that type with the name of the layout variant to resolve.

To support further types with a viewtype specific type resolution, a custom PostProcessor can be provided as bean.

Search Results

Table Of Contents

Your Internet Explorer is no longer supported.

Please use Mozilla Firefox, Google Chrome, or Microsoft Edge.