[FEATURE] Required viewer parameter (kitodo#1751)

Co-authored-by: Sebastian Meyer <sebastian.meyer@opencultureconsulting.com>

Author: markusweigelt

Classes/Controller/Embedded3dViewerController.php

@@ -39,13 +39,16 @@ public function mainAction(): ResponseInterface
             return $this->htmlResponse();
         }
 
+        // when using the component
         if (!empty($this->settings['document'])) {
             $this->assignModelFromDocument($this->getDocumentByUrl($this->settings['document']));
-        } else {
-            $this->loadDocument();
-            if (!$this->isDocMissingOrEmpty()) {
-                $this->assignModelFromDocument($this->document->getCurrentDocument());
-            }
+            return $this->htmlResponse();
+        }
+
+        $this->loadDocument();
+
+        if (!$this->isDocMissingOrEmpty()) {
+            $this->assignModelFromDocument($this->document->getCurrentDocument());
         }
 
         return $this->htmlResponse();
@@ -81,6 +84,15 @@ public function buildEmbedded3dViewerUrl(string $model = ''): string
         if (!empty($viewer)) {
             $embedded3dViewerUrl .= '&viewer=' . $viewer;
         }
+
+        if (!empty($this->requestData['viewerParam'])) {
+            $embedded3dViewerUrl .= '&' . http_build_query(['viewerParam' => $this->requestData['viewerParam']]);
+        }
+
+        if (!empty($this->settings['queryString'])) {
+            $embedded3dViewerUrl .= '&' . $this->settings['queryString'];
+        }
+
         return $embedded3dViewerUrl;
     }
 

Classes/Middleware/Embedded3dViewer.php

@@ -123,7 +123,19 @@ public function process(ServerRequestInterface $request, RequestHandlerInterface
             return $this->warningResponse('Viewer "' . $viewer . '" does not support the model format "' . $modelFormat . '"', $request);
         }
 
-        $html = $this->getViewerHtml($config, $viewerConfigPath, $viewerFolder, $parameters['model'], $modelInfo);
+        if (isset($config["requiredParameters"]) && is_array($config["requiredParameters"]) && !empty($config["requiredParameters"])) {
+            if (empty($parameters["viewerParam"])) {
+                return $this->warningResponse('The required viewer parameters do not exist', $request);
+            }
+
+            foreach ($config["requiredParameters"] as $key) {
+                if (!array_key_exists($key, $parameters["viewerParam"])) {
+                    return $this->warningResponse('Required viewer parameter "' . $key . '" does not exist', $request);
+                }
+            }
+        }
+
+        $html = $this->getViewerHtml($config, $viewerConfigPath, $viewerFolder, $parameters, $modelInfo);
         return new HtmlResponse($html);
     }
 
@@ -193,15 +205,20 @@ private function getViewerByExtensionConfiguration(string $modelFormat): string
     /**
      * @param string $viewerUrl
      * @param string $html
-     * @param string $modelUrl
+     * @param array $parameters
      * @param array $modelInfo
      * @return string
      */
-    public function replacePlaceholders(string $viewerUrl, string $html, $modelUrl, array $modelInfo): string
+    public function replacePlaceholders(string $viewerUrl, string $html, array $parameters, array $modelInfo): string
     {
         $html = str_replace("{{viewerPath}}", $viewerUrl, $html);
-        $html = str_replace("{{modelUrl}}", $modelUrl, $html);
+        $html = str_replace("{{modelUrl}}", $parameters['model'], $html);
         $html = str_replace("{{modelPath}}", $modelInfo["dirname"], $html);
+        if (!empty($parameters["viewerParam"])) {
+            foreach ($parameters["viewerParam"] as $key => $value) {
+                $html = str_replace("{{viewerParam." . $key . "}}", $value, $html);
+            }
+        }
         return str_replace("{{modelResource}}", $modelInfo["basename"], $html);
     }
 
@@ -225,11 +242,11 @@ public function renderDefaultViewer($model): HtmlResponse
      * @param array $config
      * @param string $viewerConfigPath
      * @param Folder $viewerFolder
-     * @param string $modelUrl
+     * @param array $parameters
      * @param array $modelInfo
      * @return string
      */
-    public function getViewerHtml(array $config, string $viewerConfigPath, Folder $viewerFolder, string $modelUrl, array $modelInfo): string
+    public function getViewerHtml(array $config, string $viewerConfigPath, Folder $viewerFolder, array $parameters, array $modelInfo): string
     {
         $htmlFile = "index.html";
         if (isset($config["base"]) && !empty($config["base"])) {
@@ -242,6 +259,6 @@ public function getViewerHtml(array $config, string $viewerConfigPath, Folder $v
         }
 
         $html = $viewerFolder->getFile($htmlFile)->getContents();
-        return $this->replacePlaceholders($viewerUrl, $html, $modelUrl, $modelInfo);
+        return $this->replacePlaceholders($viewerUrl, $html, $parameters, $modelInfo);
     }
 }

Configuration/FlexForms/Embedded3dViewer.xml

@@ -42,6 +42,14 @@
                             <eval>trim</eval>
                         </config>
                     </settings.viewer>
+                    <settings.queryString>
+                        <exclude>1</exclude>
+                        <label>LLL:EXT:dlf/Resources/Private/Language/locallang_be.xlf:plugins.embedded3dviewer.flexform.queryString</label>
+                        <config>
+                            <type>input</type>
+                            <eval>trim</eval>
+                        </config>
+                    </settings.queryString>
                 </el>
             </ROOT>
         </sDEF>

Documentation/Developers/Embedded3DViewer.rst

@@ -71,6 +71,10 @@ To configure the 3D viewer for Kitodo.Presentation, a ``dlf-3d-viewer.yml`` file
    - :field:                    supportedModelFormats (required)
      :description:              Specify single or multiple supported model formats of the viewer.
 
+   - :field:                    requiredParameters
+     :description:              Specify single or multiple required parameters of the viewer. (Viewer parameters are passed in URL using the array ``viewerParam`` e.g. ``viewerParam[parameterName]=parameterValue``)
+
+
 Example
 ^^^^^^^^^^^^^^^^^^^^^^^^^
 
@@ -82,6 +86,9 @@ Example
     supportedModelFormats:
       - glf
       - ply
+    requiredParameter:
+      - foo
+      - bar
 
 Placeholders
 -------
@@ -106,3 +113,6 @@ Placeholders can be used within the file which is define under the ``base`` key
    - :field:                    modelResource
      :description:              Resource part of the ``modelUrl`` with the filename to be loaded from the endpoint. For example, if your resource is hosted at "https://example.com/my-model.glb", the value would be "my-model.glb".
 
+   - :field:                    viewerParam.``parameterName``
+     :description:              Value of URL parameter ``viewerParam[parameterName]`` (Please define the parameter as requiredParameter in ``dlf-3d-viewer.yml`` file)
+

Resources/Private/Language/de.locallang_be.xlf

@@ -610,6 +610,10 @@
             <trans-unit id="plugins.embedded3dviewer.flexform.viewer">
                 <source><![CDATA[Name of viewer]]></source>
             </trans-unit>
+			<trans-unit id="plugins.embedded3dviewer.flexform.queryString">
+				<source><![CDATA[Query string added to embedded viewer URL]]></source>
+				<target><![CDATA[Query-String zur eingebetteten Viewer-URL hinzugefügt]]></target>
+			</trans-unit>
             <trans-unit id="plugins.annotation.title" approved="yes">
                 <source><![CDATA[Kitodo: Annotations]]></source>
                 <target><![CDATA[Kitodo: Annotationen]]></target>

Resources/Private/Language/locallang_be.xlf

@@ -485,6 +485,9 @@
             <trans-unit id="plugins.embedded3dviewer.flexform.viewer">
                 <source><![CDATA[Name of viewer]]></source>
             </trans-unit>
+			<trans-unit id="plugins.embedded3dviewer.flexform.queryString">
+				<source><![CDATA[Query string added to embedded viewer URL]]></source>
+			</trans-unit>
             <trans-unit id="plugins.annotation.title">
                 <source><![CDATA[Kitodo: Annotations]]></source>
             </trans-unit>