From 2f6e0c46897670001be19363855d15134156a8f3 Mon Sep 17 00:00:00 2001 From: Justin Georgi Date: Fri, 25 Oct 2024 17:25:34 -0700 Subject: [PATCH] Clean up php class and add DocBlocks Signed-off-by: Justin Georgi --- includes/GlModelViewer.php | 157 +++++++++++++++++++++++++++++++------ 1 file changed, 134 insertions(+), 23 deletions(-) diff --git a/includes/GlModelViewer.php b/includes/GlModelViewer.php index 22f9e41..6852918 100644 --- a/includes/GlModelViewer.php +++ b/includes/GlModelViewer.php @@ -2,20 +2,40 @@ use MediaWiki\MediaWikiServices; class GlModelViewer extends ImageHandler { + /** + * MWHook: Add gltf mime types to MimeMagic + * + * @see https://www.mediawiki.org/wiki/Manual:Hooks/MimeMagicInit + * + * @param MimeAnalyzer $mime Instance of MW MimeAnalyzer object + */ public static function onMimeMagicInit(MimeAnalyzer $mime) { $mime->addExtraTypes('model/gltf-binary glb gltf'); $mime->addExtraInfo('model/gltf-binary [DRAWING]'); } + /** + * MWHook: Make sure that gltf files get the proper mime assignement on upload + * + * @see https://www.mediawiki.org/wiki/Manual:Hooks/MimeMagicImproveFromExtension + * + * @param MimeAnalyzer $mimeAnalyzer Instance of MW MimeAnalyzer object + * @param string $ext extention of upload file + * @param string &$mime current assigned mime type + */ public static function onMimeMagicImproveFromExtension( MimeAnalyzer $mimeAnalyzer, $ext, &$mime ) { if ( $mime !== 'model/gltf-binary' && in_array( $ext, ['glb', 'gltf'] ) ) { $mime = 'model/gltf-binary'; } } - function doTransform($image, $dstPath, $dstUrl, $params, $flags = 0) { - } - + /** + * MWHook: Load the js and css modules if model-viewer element is found in the html output + * + * @see https://www.mediawiki.org/wiki/Manual:Hooks/BeforePageDisplay + * + * @param OutputPage $out compiled page html and manipulation methods + */ public static function onBeforePageDisplay(OutputPage $out) { preg_match('/(getHTML(),$findGltf); if ($findGltf[0]) { @@ -23,24 +43,61 @@ class GlModelViewer extends ImageHandler { } } + /** + * MWHook: Replace File link rendered image with model-viewer element + * + * @see https://www.mediawiki.org/wiki/Manual:Hooks/ImageBeforeProduceHTML + * + * @param DummyLinker &$linker + * @param Title &$title + * @param FileObject &$file object containing information regarding the actual file for the File page + * @param array &$frameParams any added parameters of the file link such as class etc. + * @param array &$handlerParams + * @param &$time + * @param &$result By reference access to the rendered html result of the image + * @param Parser $parser + * @param string &$query + * @param &$widthOption + * @return bool|void True to continue default processing or false to abort for custom processing + */ public static function onImageBeforeProduceHTML( DummyLinker &$linker, Title &$title, &$file, array &$frameParams, array &$handlerParams, &$time, &$result, Parser $parser, string &$query, &$widthOption ) { if ($file->getMimeType() !== 'model/gltf-binary') { return true; } + $result = self::buildViewer($file->getDescriptionText(), $file->getFullUrl(), $frameParams); return false; } + /** + * MWHook: Display model on file page + * + * @see https://www.mediawiki.org/wiki/Manual:Hooks/ImageOpenShowImageInlineBefore + * + * @param ImagePage $imagepage information regarding the page for the image file + * @param OutputPage $out compiled page html and manipulation methods + */ public static function onImageOpenShowImageInlineBefore( $imagepage, $out ){ $file = $imagepage->getFile(); - if ($file->getMimeType() !== 'model/gltf-binary') { - return; + if ($file->getMimeType() == 'model/gltf-binary') { + $out->addModules('ext.glmv'); + + $viewer = self::buildViewer($file->getDescriptionText(), $file->getFullUrl(), ['class' => 'view-default']); + $out->addHtml(Html::rawElement('div',['id' => 'file', 'class' => 'fullModelView'],$viewer)); } - $out->addModules('ext.glmv'); - $viewer = self::buildViewer($file->getDescriptionText(), $file->getFullUrl(), ['class' => 'view-default']); - $out->addHtml(Html::rawElement('div',['id' => 'file', 'class' => 'fullModelView'],$viewer)); } + /** + * MWHook: Display model when model file page edits are previewed + * + * @see https://www.mediawiki.org/wiki/Manual:Hooks/AlternateEditPreview + * + * @param EditPage $editor access to information about the edit page itself + * @param Content $content access to the current content of the editor + * @param string &$previewHTML by reference access to the resultant compiled preview html + * @param ?ParserOutput &$parserOutput + * @return bool|void True to continue default processing or false to abort for custom processing + */ public static function onAlternateEditPreview( EditPage $editor, Content $content, string &$previewHTML, ?ParserOutput &$parserOutput ) { $file = MediaWikiServices::getInstance()->getRepoGroup()->findFile($editor->getTitle()); if (!$file || $file->getMimeType() !== 'model/gltf-binary') { @@ -48,29 +105,39 @@ class GlModelViewer extends ImageHandler { } $out = $editor->getContext()->getOutput(); $out->addModules('ext.glmv'); + $previewViewer = self::buildViewer($content->getText(), $file->getFullUrl(), ['class' => 'view-default']); + $addButtonAttr = array( 'class' => 'AddHotspot', 'onclick' => 'readyAddHotspot()' ); $addHsButton = Html::rawElement('button',$addButtonAttr,'Add a new hotspot'); + $previewHTML = Html::rawElement('div',NULL,$previewViewer.$addHsButton); - return false; } + /** + * Build model-viewer and child elements + * + * This takes in the metadata text from the model page (or the current editor) + * and produces the html string for the model-viewer and all relevant child + * elements. + * + * @param string $inText The metadata text which must include a json formatted string inside a pre tag + * @param string $srcUrl The full url pointing to the model file + * @param array $frameParams The additional user defined parameters for the viewer such as hotspot and view classes + * @return string Html string of the complete model-viewer element inside a div container + */ private static function buildViewer($inText, $srcUrl, $frameParams) { + //Gather basic data preg_match('/
([\S\s]*?)<\/pre>/',$inText,$modelDescript);
     $metadata = json_decode($modelDescript[1], true);
-    if (isset($frameParams['class'])) {
-      preg_match('/view-(\S*)/',$frameParams['class'],$viewClassExtract);
-      $viewClass = ($viewClassExtract[1]) ? $viewClassExtract[1] : 'default';
-      preg_match('/hsset-(\S*)/',$frameParams['class'],$hsSetClassExtract);
-      $hsSetClass = ($hsSetClassExtract[1]) ? $hsSetClassExtract[1] : 'default';
-    } else {
-      $viewClass = 'default';
-      $hsSetClass = 'default';
-    }
+    $viewClass = self::extractClassParams('view',$frameParams['class']);
+    $hsSetClass = self::extractClassParams('hsset',$frameParams['class']);
+
+    //Handle annotations and annotation sets
     if (isset($metadata['annotations'])) {
       $hotspots = [];
       $annotations = [];
@@ -97,14 +164,20 @@ class GlModelViewer extends ImageHandler {
         array_push($hotspots, $elHotspot);
       }
     }
+
+    //Set viewer configurations or use basic default if none defined
     if (isset($metadata['viewerConfig']) && isset($metadata['viewerConfig'][$viewClass])) {
       $attrModelView = $metadata['viewerConfig'][$viewClass];
     } else {
       $attrModelView = array('camera-controls' => true);
     }
+
+    //Add important additional attributes and render model-viewer with hotspots
     $attrModelView = array_merge(['src' => $srcUrl, 'class' => 'mv-model', 'interpolation-decay' => '100'], $attrModelView);
     $attrModelView['style'] = 'width: 100%; height: 100%; min-height: 400px;';
     $elModel = Html::rawElement('model-viewer', $attrModelView, implode($hotspots));
+
+    //Render and return container element with model-viewer
     $attrContainer = array(
       'style' => "width: 800px; height: 600px;",
       'onmousedown' => 'clearAnnotations()',
@@ -113,16 +186,54 @@ class GlModelViewer extends ImageHandler {
     return Html::rawElement('div', $attrContainer, $elModel);
   }
 
-  public static function console_log($data, $add_script_tags = false) {
-    #Usage:
-    #echo '';
+  /**
+   * Detect and return model user params from link classes
+   * 
+   * The best way to send information in a file link is by adding classes to the
+   * link. This function parses the array of those classes and returns the information
+   * or 'default'
+   * 
+   * @param string $paramType the type of parameter to be extracted 'view'|'hsset'
+   * @param string $classList the string of class names as returned in $frameParams or default construction
+   * @return string parameter name or 'default'
+   */
+  private static function extractClassParams(string $paramType, string $classList) {
+    if (!in_array($paramType, ['view', 'hsset'])) {
+      return 'default';
+    }
+    
+    if (!isset($classList)) {
+      return 'default';
+    }
 
+    $searchString = '/' . $paramType . '-(\S*)/';
+    preg_match($searchString,$classList,$extractInfo);
+
+    return ($extractInfo[1]) ? $extractInfo[1] : 'default';
+  }
+
+  /**
+   * Small helper function to display information on the browser console
+   * 
+   * Usage:
+   * echo '';
+   * 
+   * @param $data information to display
+   * @param bool $add_script_tags true to put information is inside complete script tag
+   */
+  public static function console_log($data, $add_script_tags = false) {
     $command = 'console.log('. json_encode($data, JSON_HEX_TAG).');';
     if ($add_script_tags) {
         $command = '';
     }
     echo $command;
   }
+
+  /**
+   * ? But class won't work without it
+   */
+  function doTransform($image, $dstPath, $dstUrl, $params, $flags = 0) {
+  }
 }
\ No newline at end of file