Customizing the Client Preview

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:

Object	Description
dmsObject	Contains the object with all its properties and attributes
location	Contains the path where the client is hosted, origin, port, protocol
version	Contains the version number of the dmsObject that should be previewed
mimeType	Contains the mimetype of the document file of the referenced dmsObject
fileExtension	Contains the file extension of the document file
path	Contains the complete path to load the document file
lang	Contains the language code that the user has set, e.g. en or de
user	Contains 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>