Customizing the Client Preview

Owned by Team Kolibri (Unlicensed)
Last updated: Nov 17, 2023 by Mr. Schmittberger
4 min read

This article documents how to use dynamic plug-ins to view document files.

Remark: This documentation is valid for version 7.16 LTS and 8.16 LTS. There are some changes for version 9.x which still have to be documented.

Changing Viewer Configurations

You can override the default viewers in the client configuration at <my-custom-client-project-path>/src/assets/config/main.json.

The fileSizeLimit property (default 10485760 === 10 MB) means that files bigger than 10 MB will be shown only after a confirmation click.

The viewers.mimeType or viewers.fileExtension properties allow to match specific files (at least one should be specified).

The viewers.viewer property should contain the path to the custom .html viewer (path to file and language will be resolved as URL parameters).

Example: Add additional viewers

This code can be used until version 8.16 LTS.

Put your custom viewers in the asset folder at <my-custom-client-project-path>/src/assets and reference them in the configuration:

"preview": {
    "fileSizeLimit": 10485760,
    "viewers": [
      {
        "mimeType": ["audio/mp3", "video/mp4"],
		"fileExtension": ["mp3", "mp4"],
        "viewer": "assets/video/index.html?file=${path}#lang=${lang}"
      }
    ]
  },

Beginning with version 7.14, it is possible to set viewers (PDF.js, Monaco, Image, Video, Text, Compare) to view document files. Here is the default setup.

Remark: Beginning with version 9.0, the Viewer-Service is introduced which leads to different viewer paths. Please use "..viewer/view/api/.." instead of "..assets/_default/api/.."

For the Viewer-Service check this documentation as well: Usage of Viewer-Service

"preview": {
    "fileSizeLimit": 10485760,
    "viewers": [
    { "fileExtension": ["js", "json"], "viewer": "assets/_default/api/monaco/?path=${path}&mimeType=${mimeType}&fileExtension=${fileExtension}&lang=${lang}&theme=${theme}&language=javascript" },
    { "mimeType": ["application/json"], "viewer": "assets/_default/api/monaco/?path=${path}&mimeType=${mimeType}&fileExtension=${fileExtension}&lang=${lang}&theme=${theme}&language=javascript" },
    { "mimeType": ["text/plain"], "viewer": "assets/_default/api/monaco/?path=${path}&mimeType=${mimeType}&fileExtension=${fileExtension}&lang=${lang}&theme=${theme}" },
    { "mimeType": ["text/xml"], "viewer": "assets/_default/api/monaco/?path=${path}&mimeType=${mimeType}&fileExtension=${fileExtension}&lang=${lang}&theme=${theme}&language=xml" },
    { "mimeType": ["text/java"], "viewer": "assets/_default/api/monaco/?path=${path}&mimeType=${mimeType}&fileExtension=${fileExtension}&lang=${lang}&theme=${theme}&language=java" },
    { "mimeType": ["text/javascript"], "viewer": "assets/_default/api/monaco/?path=${path}&mimeType=${mimeType}&fileExtension=${fileExtension}&lang=${lang}&theme=${theme}&language=javascript" },
    { "mimeType": ["text/html"], "viewer": "assets/_default/api/monaco/?path=${path}&mimeType=${mimeType}&fileExtension=${fileExtension}&lang=${lang}&theme=${theme}&language=html" },
	{
      "mimeType": ["text/markdown", "text/x-web-markdown", "text/x-markdown"],
      "viewer": "assets/_default/api/monaco/?path=${path}&mimeType=${mimeType}&fileExtension=${fileExtension}&lang=${lang}&theme=${theme}&language=markdown"
    },
    {
      "mimeType": ["audio/mp3", "audio/webm", "audio/ogg", "audio/mpeg", "video/mp4", "video/webm", "video/ogg", "application/ogg"],
      "viewer": "assets/_default/api/video/?path=${path}&mimeType=${mimeType}&fileExtension=${fileExtension}&lang=${lang}&theme=${theme}"
    },
    {
      "mimeType": ["image/jpeg", "image/png", "image/apng", "image/gif", "image/svg+xml", "image/webp"],
      "viewer": "assets/_default/api/img/?path=${path}&mimeType=${mimeType}&fileExtension=${fileExtension}&lang=${lang}&theme=${theme}"
    },
    { "viewer": "() => parameters.defaultViewer + '#'" },
    { "error": true, "viewer": "assets/_default/api/error/?path=${path}&mimeType=${mimeType}&fileExtension=${fileExtension}&lang=${lang}&theme=${theme}" }
  ]
  },

Example: Resolve the viewer path dynamically 

In case you need to resolve the viewer path dynamically, use the arrow function and it will be resolved at runtime with additional parameters (component, dmsObject, parameters, api).

"preview": {
    "viewers": [
      {
		"fileExtension": ["pdf"],
        "viewer": "() => {var user = api.session.getUser(); var id = dmsObject.id; return parameters.defaultViewer + '#/' + user + '/' + id}"
      }
    ]
  },

Example: Let the browser preview the file

This configuration example shows how to load any file via the browser by applying originalPath for viewing. The difference between originalPath and path is just the encoding.

"preview": {
    "viewers": [
      {
		"fileExtension": ["pdf"],
        "viewer": "${originalPath}"
      }
    ]
  },

Example: Scripting

The following configuration example shows how to use scripting to control an additional viewer-service. For a pdf formatted file the custom microservice stampservice is called to include a watermark onto each page.

"viewers": [{
	"fileExtension": ["pdf"],
	"viewer": "() => {var viewerUrl = parameters.defaultViewer; var obj = dmsObject; if (['docdocrule','docdrawing','docreport','docchorder'].includes(obj.typeName)) {var user = api.session.getUser(); var url = 		     
                      '/ecm/stampservice/api/stamp/pdf/' + obj.content.id + '?user=' + user.name + '&version=' + obj.version; viewerUrl = viewerUrl.replace('${pathPdf}', encodeURIComponent(url));} return viewerUrl + '#'}"
}]

The following scripting example shows how use the monaco editor and control it:

"viewers": [{
      "mimeType": ["text/xml"],
      "viewer": "() => {var obj = dmsObject; var url = location.origin + '/ecm/xmlformatservice/api/format/xml/' + obj.id + '?version=' + obj.version; return 'viewer/view/api/monaco/?path=' + encodeURIComponent(url) + 
                       '&mimeType=${mimeType}&fileExtension=${fileExtension}&lang=${lang}&theme=${theme}&language=xml'}"
}]



The following objects are available beside the complete client API for scripting:

ObjectDescription
dmsObjectContains the object with all its properties and attributes
locationContains the path where the client is hosted, origin, port, protocol 
versionContains the version number of the dmsObject that should be previewed
mimeTypeContains the mimetype of the document file of the referenced dmsObject 
fileExtensionContains the file extension of the document file
pathContains the complete path to load the document file
langContains the language code that the user has set, e.g. en or de
userContains the user with all his attributes

Example: Use of scripts for extension

This section is under work.

This configuration example shows how to catch events and push the refresh button to load the object details again:

"viewers": [{
	"type": "extend",
	"viewer": "() => { <script example> }"
}]

Building Your Custom Viewer

Parse the file path or language information from window.location and apply it to your component. Use <base href="/"> and place the .html file in the assets folder. 

index.html
<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <title>Video</title>
    <base href="/">
    <meta name="viewport" content="width=device-width, initial-scale=1" />
  </head>
  <body style="margin:0;">
    <video id="video" controls="" name="media" style="width:100%;height:auto;outline:none;"></video>
    <script>
     window.addEventListener('load', function() {
          document.querySelector('#video').setAttribute('src', decodeURIComponent(window.location.search.replace('?file=', '')));
      })
    </script>
  </body>
</html>