headless.js

The headless.js entry point is used to describe what the WebApp should expose in a headless context. When implemented, its output will be included in the /contentnodes and /headless endpoints of Sitevision's built in REST API. Media content will also be included in the e-plikt RSS feed. The headless.js file needs to be placed directly under the WebApp's /src folder.

The entry point has access to the Sitevision Public API, Server side SDK and any server side utility included in the WebApp.

The WebApp's headless output should be returned using the getHeadlessContent function that is available using the import below.

import { getHeadlessContent } from '@sitevision/api/server/headless';

Below is an example of how content can be exposed.

import { getHeadlessContent } from '@sitevision/api/server/headless';
import appData from '@sitevision/api/server/appData';
import properties from '@sitevision/api/server/Properties';

getHeadlessContent((params) => {
  const imagesFolder = appData.getNode('imagesFolder');
  const filesFolder = appData.getNode('filesFolder');
  const images = properties.getArray(
    imagesFolder.getNodes(),
    'URL',
    'mimeType',
    'displayName'
  );
  const files = properties.getArray(
    filesFolder.getNodes(),
    'URL',
    'mimeType',
    'displayName'
  );

  return [
    {
      type: 'images',
      properties: {
        images,
      },
    },
    {
      type: 'files',
      properties: {
        files,
      },
    },
  ];
});

Supported content

The following types are supported as headless output:

  • image
  • images
  • files
  • video
  • text

image example

{
   "type": "image",
   "properties": {
      "image": {
         "displayName": "alle.jpg",
         "alt": "En vacker allé ",
         "mimeType": "image/jpeg",
         "URI": "/images/18.156d4f8a180b6f149dc342/1652338636750/alle.jpg",
         "URL": "http://localhost/images/18.156d4f8a180b6f149dc342/1652338636750/alle.jpg",
         "id": "18.156d4f8a180b6f149dc342"
      }
   }
}

images example

{
   "type": "images",
   "properties": {
      "images": [
         {
            "displayName": "alle.jpg",
            "alt": "En vacker allé ",
            "mimeType": "image/jpeg",
            "URI": "/images/18.156d4f8a180b6f149dc342/1652338636750/alle.jpg",
            "URL": "http://localhost/images/18.156d4f8a180b6f149dc342/1652338636750/alle.jpg",
            "id": "18.156d4f8a180b6f149dc342"
          },
          {
            "displayName": "blad.jpg",
            "alt": "Massor av blad",
            "mimeType": "image/jpeg",
            "URI": "/images/18.156d4f8a180b6f149dc340/1652338636721/blad.jpg",
            "URL": "http://localhost/images/18.156d4f8a180b6f149dc340/1652338636721/blad.jpg",
            "id": "18.156d4f8a180b6f149dc340"
          }
      ]
   }
}

files example

{
   "type": "files",
   "properties": {
      "files": [
         {
            "mimeType": "application/pdf",
            "URL": "http://localhost/download/18.2e5ba6241811a92bf375/1654084543526/certificate.pdf",
            "displayName": "certificate.pdf"
         },
         {
            "mimeType": "application/pdf",
            "URL": "http://localhost/download/18.2e5ba6241811a92bf376/1654084543601/calendar-2022-06.pdf",
            "displayName": "calendar-2022-06.pdf"
         }
      ]
   }
}

video example

{
   "type": "video",
   "properties": {
      "video": {
         "id": "18.708f851f1814270e7e11",
         "displayName": "sample-mp4-file.mp4",
         "mimeType": "video/mp4",
         "streamURI": "/download-streamed/18.708f851f1814270e7e11/1654677380149/sample-mp4-file.mp4",
         "streamURL": "http://localhost/download-streamed/18.708f851f1814270e7e11/1654677380149/sample-mp4-file.mp4",
         "URI": "/download/18.708f851f1814270e7e11/1654677380149/sample-mp4-file.mp4",
         "URL": "http://localhost/download/18.708f851f1814270e7e11/1654677380149/sample-mp4-file.mp4"
      }
   }
}

text example

textContent comes in two formats: JSON or PLAIN (default). Check the params.textPortletFormat value to find out which format should be returned.

// params.textPortletFormat === 'PLAIN'
{
   "type": "text",
   "properties": {
      "textContent": "Hello, world!"
   }
}
// params.textPortletFormat === 'JSON'
{
   "type": "text",
   "properties": {
      "textContent": [
         {
            "type": "block",
            "htmlName": "p",
            "attributes": {},
            "children": [
               {
                  "type": "text",
                  "content": "Hello, world!"
               }
            ]
         }
      ]
   }
}

Please refer to the /headless endpoint documentation in Sitevision's built in REST API for more information on how the JSON result should be formatted.

Validation

The output needs to be structured according to the examples above.

  • Returned content must be an array of objects with type and properties keys
  • The properties object must be structured according to its type, see examples above
  • Media content requires URL and displayName to be specified, other attributes are optional
    • mimeType is required if the content is intended to be included in the e-plikt RSS feed

Before headless output is included in any API response/RSS feed, it will be validated to make sure it matches the expected format. If validation fails, all of the output will be omitted. See the server.log for error messages related to headless output validation.