Delivering content

Loading content from Mesh

The portal loads page content from Mesh via the loadByPath GraphQL query. The portal framework already comes with a loadByPath.graphql that has the necessary structure so that the response can be processed correctly. What the query returns exactly is specified in the query fragments

  • breadcrumbFields

  • contentFields

  • folderFields

  • folderContentsFields, and

  • parentInfo

which can be overridden with custom values. Complete GraphQL queries can be overridden by putting them in the configured queryPath or queryPath/fragments directories. The filenames containing fragments must be exactly the fragment name with the extension .graphql.

For most use cases it should only be necessary to adapt the contentFields fragment. The default contentFields fragment looks like this, and should be extended to load all necessary fields defined in the tagmap:

fragment contentFields on %contentSchema% {
  title(linkType: SHORT)
  teaser(linkType: SHORT)
  pagecontent(linkType: SHORT)


The portal will periodically load navigation information from Mesh via the loadNavigation GraphQL query. The structure of this query and its fragment navigation should not be changed, or the navigation helpers might not work as expected.

By default the query will load folders up to a depth of six and the result will provide information about the name, sort order and start page of the folders.

The loaded navigation information is cached depending on user roles, and will be cleared each minute, or when folders or pages are published by the CMS.

Preview handling

The Gentics CMS will use the /api/preview endpoint to render pages for preview or edit mode, with a query parameter to distinguish betweeen the two cases.

Preview modes

The portal distinguishes between the following render modes:

  • UNKNOWN: The page is rendered as a preview, but the exact mode is not available.

    This will happen when an older version of the Gentics CMS is used, which does not yet provide the necessary information for the /api/preview endpoint

  • PREVIEW: The page is being previewed (but not edited) in the Gentics CMS

  • EDIT: The page is being edited in the Gentics CMS

  • PUBLISH: The published version of the page is viewed in the front-end

Working with the render mode in the templates

The following Handlebars helpers can be used to distinguish the different modes a page can be viewed:

  • {{ getRenderMode }} will just print print the current preview mode, and is intended for debugging purposes

  • {{# renderMode 'mode' }} will evaluate the enclosed block only if the current preview mode is mode

Working with the render mode in the portal

When data is POSTed to /api/preview the ContentPreviewHandler will enable preview mode by calling PortalRoutingContext#enablePreview(). This will in turn try to determine the exact mode by looking at the renderMode query parameter.

When this value is preview or edit the respective preview mode is set, otherwise it will be UNKNOWN. In either case PortalRoutingContext#isPreview() will return true from now on, so that the following handlers can react to the preview mode.

When compatibility mode for previews is active, the portal will not distinguish between PREVIEW and EDIT mode. All requests to the /api/preview endpoint will set the mode to PREVIEW.

Delivering Multi-language content

The portal will always deliver content pages in the language that matches the requested path, but the preferred language is saved in the cookie mesh.portal.language, and will be used for example to display the

  • configured start page, or

  • error pages

in the correct language.

Only one language has to be configured for the startPage or in the redirect.statusPages mapping,[1] but before showing the start page or the respective error page, the portal will try to lookup the path for the page in the correct language.

When a page is not available in the preferred language, the path from the configuration is used as is.

These mappings are cached and use the default caching.expireTime configuration.

Determining the preferred language

The portal will choose the preferred language from one of these sources (in descending priority):

  1. The value of the mesh.portal.language cookie

  2. The language of the currently loaded Mesh node

  3. The Accept-Language HTTP header

  4. The configured defaultLanguage

Note that previews in the Gentics CMS will ignore the language cookie.

When the portal has chosen a language and did not have to fallback to the default language, the response will contain the cookie to use the language for future requests. Requesting a page in a different language than specified in the cookie will not change the value of the cookie since the already set cookie has a higher priority than the current page language for determining the preferred language. The actual language of the served page is available in the routing context with the key [mesh.portal.node.language].

Setting the preferred language explicitly

The preferred language can be set by a request to the endpoint /api/language with the lang query parameter. The response will set the language cookie accordingly, so that future requests will prefer the specified language.

When the redirect query parameter is set, the response will redirect to the specified path. Note that the value will be sanitized so that it does not contain a protocol or domain to prevent redirection to an external site.[2]

The Referer HTTP header will be used when it is present and the redirect parameter is missing (the referer URL will not be sanitized).

When neither the redirect parameter nor the Referer header are present, the portal will respond with an empty 200 OK answer.

1. Actually only one path can be configured.
2. For example the redirect URL http://some.other.domain/path will be sanitized to /path.